create_embedded_invite_from_template
Generate embedded signing invites directly from templates to collect electronic signatures without document preparation delays.
Instructions
Create document/group from template and create embedded invite immediately
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ID of the template or template group | |
| entity_type | No | Type of entity: 'template' or 'template_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. | |
| name | No | Optional name for the new document or document group | |
| orders | No | List of orders with recipients for the embedded invite |
Input Schema (JSON Schema)
{
"properties": {
"entity_id": {
"description": "ID of the template or template group",
"title": "Entity Id",
"type": "string"
},
"entity_type": {
"anyOf": [
{
"enum": [
"template",
"template_group"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Type of entity: 'template' or 'template_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"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional name for the new document or document group",
"title": "Name"
},
"orders": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/EmbeddedInviteOrder"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "List of orders with recipients for the embedded invite",
"title": "Orders"
}
},
"required": [
"entity_id"
],
"type": "object"
}
Implementation Reference
- src/sn_mcp_server/tools/signnow.py:498-502 (registration)Tool registration with @mcp.tool decorator specifying name, description, and tags.@mcp.tool( name="create_embedded_invite_from_template", description="Create document/group from template and create embedded invite immediately", tags=["template", "template_group", "document", "document_group", "send_invite", "embedded", "workflow"], )
- Primary handler function that handles input validation, token retrieval, order normalization, and delegates to the helper function for core logic execution.async def create_embedded_invite_from_template( ctx: Context, entity_id: Annotated[str, Field(description="ID of the template or template group")], orders: Annotated[ list[EmbeddedInviteOrder] | str | None, Field( description="List of orders with recipients for the embedded invite (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["template", "template_group"] | None, Field(description="Type of entity: 'template' or 'template_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, name: Annotated[str | None, Field(description="Optional name for the new document or document group")] = None, ) -> CreateEmbeddedInviteFromTemplateResponse: """Create document or document group from template and create embedded invite immediately. This tool combines two operations: 1. Creates a document/group from template using create_from_template 2. Creates an embedded invite for the created entity using create_embedded_invite Args: entity_id: ID of the template or template group orders: List of orders with recipients for the embedded invite (can be a list or JSON string) entity_type: Type of entity: 'template' or 'template_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. name: Optional name for the new document or document group Returns: CreateEmbeddedInviteFromTemplateResponse with created entity info and embedded invite details """ 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 await _create_embedded_invite_from_template(entity_id, entity_type, name, normalized_orders, token, client, ctx)
- Core helper function implementing the logic: creates document/group from template, then creates embedded invite, reports progress, handles both document and document_group cases.async def _create_embedded_invite_from_template( entity_id: str, entity_type: Literal["template", "template_group"] | None, name: str | None, orders: list[EmbeddedInviteOrder], token: str, client: SignNowAPIClient, ctx: Context, ) -> CreateEmbeddedInviteFromTemplateResponse: """Private function to create document/group from template and create embedded invite immediately. Args: entity_id: ID of the template or template group entity_type: Type of entity: 'template' or 'template_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. name: Optional name for the new document or document group orders: List of orders with recipients for the embedded invite token: Access token for SignNow API client: SignNow API client instance ctx: FastMCP context for progress reporting Returns: CreateEmbeddedInviteFromTemplateResponse with created entity info and embedded invite details """ # Report initial progress await ctx.report_progress(progress=1, total=3) # Import and use the create from template function directly from .create_from_template import _create_from_template # Use the imported function to create from template created_entity = _create_from_template(entity_id, entity_type, name, token, client) # Report progress after template creation await ctx.report_progress(progress=2, total=3) if created_entity.entity_type == "document_group": # Create document group embedded invite document_group = client.get_document_group(token, created_entity.entity_id) invite_response = _create_document_group_embedded_invite(client, token, created_entity.entity_id, orders, document_group) # Report final progress after embedded invite creation await ctx.report_progress(progress=3, total=3) return CreateEmbeddedInviteFromTemplateResponse( created_entity_id=created_entity.entity_id, created_entity_type=created_entity.entity_type, created_entity_name=created_entity.name, invite_id=invite_response.invite_id, invite_entity=invite_response.invite_entity, recipient_links=invite_response.recipient_links, ) else: # Create document embedded invite invite_response = _create_document_embedded_invite(client, token, created_entity.entity_id, orders) # Report final progress after embedded invite creation await ctx.report_progress(progress=3, total=3) return CreateEmbeddedInviteFromTemplateResponse( created_entity_id=created_entity.entity_id, created_entity_type=created_entity.entity_type, created_entity_name=created_entity.name, invite_id=invite_response.invite_id, invite_entity=invite_response.invite_entity, recipient_links=invite_response.recipient_links, )
- Pydantic models for request and response schemas, including input validation for parameters and output structure with created entity and invite details.class CreateEmbeddedInviteFromTemplateRequest(BaseModel): """Request model for creating document/group from template and creating embedded invite immediately.""" entity_id: str = Field(..., description="ID of the template or template group") entity_type: str | None = Field(None, description="Type of entity: 'template' or 'template_group' (optional)") name: str | None = Field(None, description="Optional name for the new document or document group") orders: list[EmbeddedInviteOrder] = Field(default=[], description="List of orders with recipients for the embedded invite") redirect_uri: str | None = Field(None, description="Optional redirect URI after completion") redirect_target: str | None = Field(None, description="Optional redirect target: 'self', 'blank', or 'self' (default)") link_expiration: int | None = Field(None, ge=15, le=43200, description="Optional link expiration in minutes (15-43200)") 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 CreateEmbeddedInviteFromTemplateResponse(BaseModel): """Response model for creating document/group from template and creating embedded invite immediately.""" created_entity_id: str = Field(..., description="ID of the created document or document group") created_entity_type: str = Field(..., description="Type of created entity: 'document' or 'document_group'") created_entity_name: str = Field(..., description="Name of the created entity") 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'")