get_invite_status
Check the status of signing invitations for documents or document groups in SignNow to monitor signature progress and completion.
Instructions
Get invite status for a document or document group
Input Schema
TableJSON 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. |
Implementation Reference
- Primary handler function decorated with @mcp.tool(). Defines input schema via Annotated[Field], handles token retrieval, creates API client, and delegates to _get_invite_status helper.@mcp.tool(name="get_invite_status", description="Get invite status for a document or document group", tags=["invite", "status", "document", "document_group", "workflow"]) def get_invite_status( ctx: Context, entity_id: Annotated[str, Field(description="ID of the document or document group")], 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, ) -> InviteStatus: """Get invite status for 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. Returns: InviteStatus with invite ID, status, and steps information """ headers = get_http_headers() token = token_provider.get_access_token(headers) if not token: raise ValueError("No access token available") # Initialize client and use the imported function from invite_status module client = SignNowAPIClient(token_provider.signnow_config) return _get_invite_status(entity_id, entity_type, token, client)
- Core helper function implementing the logic to fetch document or document group data, determine type if needed, and call specific status extractors to build InviteStatus response.def _get_invite_status(entity_id: str, entity_type: Literal["document", "document_group"] | None, token: str, client: SignNowAPIClient) -> InviteStatus: """Private function to get invite status for 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. token: Access token for SignNow API client: SignNow API client instance Returns: InviteStatus with invite ID, status, and steps information """ # Determine entity type if not provided and get entity data document_group = None document = None 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_v2(token, entity_id) entity_type = "document_group" except Exception: # If document group not found, try document try: document = 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 else: # Entity type is provided, get the entity data if entity_type == "document_group": document_group = client.get_document_group_v2(token, entity_id) else: document = client.get_document(token, entity_id) if entity_type == "document_group": # Get document group status using the already fetched data return _get_document_group_status(client, token, document_group, entity_id) else: # Get document status using the already fetched data return _get_document_status(client, token, document)
- Pydantic output schema model InviteStatus defining the structure of the tool response, including invite_id, status, and steps.class InviteStatus(BaseModel): """Complete status information for an invite.""" invite_id: str = Field(..., description="ID of the invite") status: str = Field(..., description="Overall invite status: 'created', 'pending', 'fulfilled'") steps: list[DocumentGroupStatusStep] = Field(..., description="List of steps in the invite")
- src/sn_mcp_server/tools/signnow.py:550-550 (registration)The @mcp.tool decorator line registering the tool with name, description, and tags.@mcp.tool(name="get_invite_status", description="Get invite status for a document or document group", tags=["invite", "status", "document", "document_group", "workflow"])
- Supporting helper to extract and transform document group invite status from API response.def _get_document_group_status(client: SignNowAPIClient, token: str, document_group_data: Any, document_group_id: str) -> InviteStatus: """ Get document group status information. This function extracts invite_id from document group data, then gets field invite details and returns formatted status information. Args: client: SignNow API client instance token: Access token for authentication document_group_data: Document group data document_group_id: ID of the document group Returns: InviteStatus with invite_id, status, and steps information Raises: ValueError: If group not found or no invite_id found """ group_response = document_group_data invite_id = group_response.data.invite_id if not invite_id: raise ValueError(f"No invite_id found for document group {document_group_id}") # Get field invite details invite_response = client.get_field_invite(token, document_group_id, invite_id) invite = invite_response.invite # Transform steps and actions to our format steps = [] for step in invite.steps: actions = [] for action in step.actions: # Only include actions with email (skip email_group actions) if action.email: actions.append(DocumentGroupStatusAction(action=action.action, email=action.email, document_id=action.document_id, status=action.status, role=action.role_name)) steps.append(DocumentGroupStatusStep(status=step.status, order=step.order, actions=actions)) return InviteStatus(invite_id=invite.id, status=invite.status, steps=steps)