send_invite
Send signing invitations for documents or document groups to recipients with defined roles and actions.
Instructions
Send invite to sign a document or document group. This tool is ONLY for documents and document groups. If you have template or template_group, use the alternative tool: send_invite_from_template
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ID of the document or document group | |
| orders | No | List of orders with recipients (can be a list or JSON string) | |
| entity_type | No | Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. |
Implementation Reference
- The primary handler function for the 'send_invite' MCP tool. It handles input normalization, retrieves authentication token and client, and delegates to the _send_invite helper function to execute the core logic.name="send_invite", description=( "Send invite to sign a document or document group. " "This tool is ONLY for documents and document groups. " "If you have template or template_group, use the alternative tool: send_invite_from_template" ), tags=["send_invite", "document", "document_group", "sign", "workflow"], ) def send_invite( ctx: Context, entity_id: Annotated[str, Field(description="ID of the document or document group")], orders: Annotated[ list[InviteOrder] | str | None, Field( description="List of orders with recipients (can be a list or JSON string)", examples=[ [{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}], '[{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}]', ], ), ] = None, entity_type: Annotated[ Literal["document", "document_group"] | None, Field(description="Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type."), ] = None, ) -> SendInviteResponse: """Send invite to sign a document or document group. This tool is ONLY for documents and document groups. If you have template or template_group, use the alternative tool: send_invite_from_template Args: entity_id: ID of the document or document group orders: List of orders with recipients (can be a list or JSON string) entity_type: Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. Returns: SendInviteResponse with invite ID and entity type """ token, client = _get_token_and_client(token_provider) # Normalize orders parameter (handle JSON string input) normalized_orders = _normalize_orders(orders, InviteOrder) # Initialize client and use the imported function from send_invite module return _send_invite(entity_id, entity_type, normalized_orders, token, client)
- src/sn_mcp_server/tools/signnow.py:201-247 (registration)The @mcp.tool decorator that registers the 'send_invite' tool with FastMCP, including name, description, tags, and input parameters.name="send_invite", description=( "Send invite to sign a document or document group. " "This tool is ONLY for documents and document groups. " "If you have template or template_group, use the alternative tool: send_invite_from_template" ), tags=["send_invite", "document", "document_group", "sign", "workflow"], ) def send_invite( ctx: Context, entity_id: Annotated[str, Field(description="ID of the document or document group")], orders: Annotated[ list[InviteOrder] | str | None, Field( description="List of orders with recipients (can be a list or JSON string)", examples=[ [{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}], '[{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}]', ], ), ] = None, entity_type: Annotated[ Literal["document", "document_group"] | None, Field(description="Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type."), ] = None, ) -> SendInviteResponse: """Send invite to sign a document or document group. This tool is ONLY for documents and document groups. If you have template or template_group, use the alternative tool: send_invite_from_template Args: entity_id: ID of the document or document group orders: List of orders with recipients (can be a list or JSON string) entity_type: Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. Returns: SendInviteResponse with invite ID and entity type """ token, client = _get_token_and_client(token_provider) # Normalize orders parameter (handle JSON string input) normalized_orders = _normalize_orders(orders, InviteOrder) # Initialize client and use the imported function from send_invite module return _send_invite(entity_id, entity_type, normalized_orders, token, client)
- Pydantic model for the response of the send_invite tool.class SendInviteResponse(BaseModel): """Response model for sending invite.""" invite_id: str = Field(..., description="ID of the created invite") invite_entity: str = Field(..., description="Type of invite entity: 'document' or 'document_group'")
- Pydantic model for invite orders used as input to send_invite.class InviteOrder(BaseModel): """Order information for invite.""" order: int = Field(..., description="Order number for this step") recipients: list[InviteRecipient] = Field(..., description="List of recipients for this order")
- Core helper function implementing the send invite logic, including entity type detection, and delegating to document-specific or document group-specific invite functions.def _send_invite(entity_id: str, entity_type: Literal["document", "document_group"] | None, orders: list[InviteOrder], token: str, client: SignNowAPIClient) -> SendInviteResponse: """Private function to send invite to sign a document or document group. Args: entity_id: ID of the document or document group entity_type: Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. orders: List of orders with recipients token: Access token for SignNow API client: SignNow API client instance Returns: SendInviteResponse with invite ID and entity type """ # Determine entity type if not provided document_group = None # Store document group if found during auto-detection if not entity_type: # Try to determine entity type by attempting to get document group first (higher priority) try: document_group = client.get_document_group(token, entity_id) entity_type = "document_group" except Exception: # If document group not found, try document try: client.get_document(token, entity_id) entity_type = "document" except Exception: raise ValueError(f"Entity with ID {entity_id} not found as either document group or document") from None if entity_type == "document_group": # Send document group field invite # Get the document group if we don't have it yet if not document_group: document_group = client.get_document_group(token, entity_id) return _send_document_group_field_invite(client, token, entity_id, orders, document_group) else: # Send document field invite return _send_document_field_invite(client, token, entity_id, orders)