create_embedded_invite
Generate embedded signing invites for documents or document groups to collect electronic signatures from recipients.
Instructions
Create embedded invite for signing a document or document group
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ID of the document or document group | |
| 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. | |
| orders | No | List of orders with recipients |
Input Schema (JSON Schema)
{
"properties": {
"entity_id": {
"description": "ID of the document or document group",
"title": "Entity Id",
"type": "string"
},
"entity_type": {
"anyOf": [
{
"enum": [
"document",
"document_group"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"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.",
"title": "Entity Type"
},
"orders": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/EmbeddedInviteOrder"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "List of orders with recipients",
"title": "Orders"
}
},
"required": [
"entity_id"
],
"type": "object"
}
Implementation Reference
- MCP tool handler for 'create_embedded_invite'. Normalizes orders, retrieves auth token, initializes SignNow client, and calls the core _create_embedded_invite helper.name="create_embedded_invite", description="Create embedded invite for signing a document or document group", tags=["send_invite", "document", "document_group", "sign", "embedded", "workflow"], ) def create_embedded_invite( ctx: Context, entity_id: Annotated[str, Field(description="ID of the document or document group")], orders: Annotated[ list[EmbeddedInviteOrder] | 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", "auth_method": "none"}]}], '[{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign", "auth_method": "none"}]}]', ], ), ] = 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, ) -> CreateEmbeddedInviteResponse: """Create embedded invite for signing a document or document group. This tool is ONLY for documents and document groups. If you have template or template group, you have to convert it to document or document group first, using create_from_template tool 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: CreateEmbeddedInviteResponse with invite ID and entity type """ headers = get_http_headers() token = token_provider.get_access_token(headers) if not token: raise ValueError("No access token available") # Normalize orders parameter (handle JSON string input) normalized_orders = _normalize_orders(orders, EmbeddedInviteOrder) # Initialize client and use the imported function from embedded_invite module client = SignNowAPIClient(token_provider.signnow_config) return _create_embedded_invite(entity_id, entity_type, normalized_orders, token, client)
- Core helper function that dispatches to document or document_group specific embedded invite creation based on entity type. Handles auto-detection of entity type if not provided.def _create_embedded_invite( entity_id: str, entity_type: Literal["document", "document_group"] | None, orders: list[EmbeddedInviteOrder], token: str, client: SignNowAPIClient ) -> CreateEmbeddedInviteResponse: """Private function to create embedded invite for signing 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: CreateEmbeddedInviteResponse 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 # Validate orders if not orders: raise ValueError("At least one order with recipients is required") if entity_type == "document_group": # Create document group embedded 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 _create_document_group_embedded_invite(client, token, entity_id, orders, document_group) else: # Create document embedded invite return _create_document_embedded_invite(client, token, entity_id, orders)
- Pydantic schema models: EmbeddedInviteRecipient, EmbeddedInviteOrder (input), CreateEmbeddedInviteResponse (output) for the create_embedded_invite tool.class EmbeddedInviteRecipient(BaseModel): """Recipient information for embedded invite.""" email: str = Field(..., description="Recipient's email address") role: str = Field(..., description="Recipient's role name in the document") action: str = Field(default="sign", description="Allowed action with a document. Possible values: 'view', 'sign', 'approve'") auth_method: str = Field("none", description="Authentication method in integrated app: 'password', 'email', 'mfa', 'biometric', 'social', 'other', 'none'") first_name: str | None = Field(None, description="Recipient's first name") last_name: str | None = Field(None, description="Recipient's last name") redirect_uri: str | None = Field(None, description="Link that opens after completion") decline_redirect_uri: str | None = Field(None, description="URL that opens after decline") close_redirect_uri: str | None = Field(None, description="Link that opens when clicking 'Close' button") redirect_target: str | None = Field("self", description="Redirect target: 'blank' for new tab, 'self' for same tab") subject: str | None = Field(None, description="Invite email subject (max 1000 chars)") message: str | None = Field(None, description="Invite email message (max 5000 chars)") delivery_type: str | None = Field("link", description="Invite delivery method: 'email' or 'link', use 'link' if you wand to get a link to sign. If you want to send an email, use 'email'") def model_dump(self, **kwargs: Any) -> dict[str, Any]: """Override model_dump to exclude redirect_target if redirect_uri is not provided.""" data = super().model_dump(**kwargs) if (not self.redirect_uri or not self.redirect_uri.strip()) and "redirect_target" in data: del data["redirect_target"] return data class EmbeddedInviteOrder(BaseModel): """Order information for embedded invite.""" order: int = Field(..., description="Order number for this step") recipients: list[EmbeddedInviteRecipient] = Field(..., description="List of recipients for this order") class CreateEmbeddedInviteRequest(BaseModel): """Request model for creating embedded invite.""" entity_id: str = Field(..., description="ID of the document or document group") entity_type: str | None = Field(None, description="Type of entity: 'document' or 'document_group'") orders: list[EmbeddedInviteOrder] = Field(..., description="List of orders with recipients") class CreateEmbeddedInviteResponse(BaseModel): """Response model for creating embedded invite.""" invite_id: str = Field(..., description="ID of the created embedded invite") invite_entity: str = Field(..., description="Type of invite entity: 'document' or 'document_group'") recipient_links: list[dict[str, str]] = Field(..., description="Array of objects with role and link for recipients with delivery_type='link'")
- Specific helper for creating embedded invites on document groups, including signer/step construction, API call, and link generation for 'link' delivery.def _create_document_group_embedded_invite(client: SignNowAPIClient, token: str, entity_id: str, orders: list[Any], document_group: Any) -> CreateEmbeddedInviteResponse: """Private function to create document group embedded invite.""" from signnow_client import ( CreateEmbeddedInviteRequest as SignNowEmbeddedInviteRequest, ) from signnow_client import EmbeddedInviteSigner, EmbeddedInviteStep # Convert orders to embedded invite steps invite_steps = [] for order_info in orders: signers = [] for recipient in order_info.recipients: # Create EmbeddedInviteSigner for each recipient signer_data = { "email": recipient.email, "auth_method": recipient.auth_method, "first_name": recipient.first_name, "last_name": recipient.last_name, "language": "en", # Default language "required_preset_signature_name": None, "redirect_uri": recipient.redirect_uri, "decline_redirect_uri": recipient.decline_redirect_uri, "close_redirect_uri": recipient.close_redirect_uri, "delivery_type": recipient.delivery_type, "subject": recipient.subject, "message": recipient.message, "documents": [{"id": doc.id, "role": recipient.role, "action": recipient.action} for doc in document_group.documents if recipient.role in doc.roles], } # Only add redirect_target if redirect_uri is provided and not empty if recipient.redirect_uri and recipient.redirect_uri.strip(): signer_data["redirect_target"] = recipient.redirect_target signer = EmbeddedInviteSigner(**signer_data) signers.append(signer) step = EmbeddedInviteStep(order=order_info.order, signers=signers) invite_steps.append(step) request_data = SignNowEmbeddedInviteRequest(invites=invite_steps, sign_as_merged=True) # Send as merged document group response = client.create_embedded_invite(token, entity_id, request_data) # Generate links for recipients with delivery_type='link' recipient_links = [] for order_info in orders: for recipient in order_info.recipients: if recipient.delivery_type == "link": from signnow_client import GenerateEmbeddedInviteLinkRequest link_request = GenerateEmbeddedInviteLinkRequest(email=recipient.email, auth_method=recipient.auth_method) link_response = client.generate_embedded_invite_link(token, entity_id, response.data.id, link_request) recipient_links.append({"role": recipient.role, "link": link_response.data.link}) return CreateEmbeddedInviteResponse(invite_id=response.data.id, invite_entity="document_group", recipient_links=recipient_links)
- Specific helper for creating embedded invites on individual documents, including invite construction, API call, and link generation for 'link' delivery.def _create_document_embedded_invite(client: SignNowAPIClient, token: str, entity_id: str, orders: list[Any]) -> CreateEmbeddedInviteResponse: """Private function to create document embedded invite.""" from signnow_client import ( CreateDocumentEmbeddedInviteRequest, DocumentEmbeddedInvite, ) # Convert orders to document embedded invite invites = [] for order_info in orders: signers = [] for recipient in order_info.recipients: # Create DocumentEmbeddedInvite for each recipient invite_data = { "email": recipient.email, "auth_method": recipient.auth_method, "first_name": recipient.first_name, "last_name": recipient.last_name, "language": "en", # Default language "required_preset_signature_name": None, "redirect_uri": recipient.redirect_uri, "decline_redirect_uri": recipient.decline_redirect_uri, "close_redirect_uri": recipient.close_redirect_uri, "delivery_type": recipient.delivery_type, "subject": recipient.subject, "message": recipient.message, "documents": [{"id": entity_id, "role": recipient.role, "action": recipient.action}], } # Only add redirect_target if redirect_uri is provided and not empty if recipient.redirect_uri and recipient.redirect_uri.strip(): invite_data["redirect_target"] = recipient.redirect_target doc_invite = DocumentEmbeddedInvite(**invite_data) signers.append(doc_invite) invites.append({"order": str(order_info.order), "signers": signers}) request_data = CreateDocumentEmbeddedInviteRequest(invites=invites) response = client.create_document_embedded_invite(token, entity_id, request_data) # Generate links for recipients with delivery_type='link' recipient_links = [] for order_info in orders: for recipient in order_info.recipients: if recipient.delivery_type == "link": from signnow_client import GenerateDocumentEmbeddedInviteLinkRequest link_request = GenerateDocumentEmbeddedInviteLinkRequest(email=recipient.email, auth_method=recipient.auth_method) link_response = client.generate_document_embedded_invite_link(token, entity_id, response.data.id, link_request) recipient_links.append({"role": recipient.role, "link": link_response.data.link}) return CreateEmbeddedInviteResponse(invite_id=response.data.id, invite_entity="document", recipient_links=recipient_links)