Skip to main content

​
Endpoint

GET /tasks/{task_id}/signature-details

​
Authentication

This endpoint requires authentication via API key. Include your API key in the X-API-Key header: 
X-API-Key: ca_your_api_key_here

​
Path Parameters

ParameterTypeRequiredDescription
task_idintegerYesUnique identifier for the task

​
Query Parameters

ParameterTypeRequiredDescription
create_envelope_urlbooleanNoInclude the coordinator envelope URL (edit or view) when available. Defaults to false

​
Request Example

curl -X GET "https://platform.chamelio.ai/tasks/12345/signature-details?create_envelope_url=true" \
  -H "X-API-Key: ca_your_api_key_here"

import requests

task_id = 12345

url = f"https://platform.chamelio.ai/tasks/{task_id}/signature-details"
headers = {
    "X-API-Key": "ca_your_api_key_here"
}
params = {
    "create_envelope_url": True
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const taskId = 12345;

const response = await fetch(
  `https://platform.chamelio.ai/tasks/${taskId}/signature-details?create_envelope_url=true`,
  {
    method: 'GET',
    headers: {
      'X-API-Key': 'ca_your_api_key_here'
    }
  }
);

const data = await response.json();
console.log(data);

​
Response

​
Success Response

Status Code: 200 OK 
{
  "step_run": {
    "step_run_id": "sr_abc123",
    "step_id": "signature_step",
    "step_name": "Counterparty Signature",
    "step_type": "signature",
    "status": "in_progress",
    "variables": [
      {
        "variable_type": "file",
        "value": "document_456",
        "step_id": "generation_step",
        "variable_id": "signing_document"
      }
    ]
  },
  "signature_status": "sent",
  "coordinator_user_id": 42,
  "recipients": [
    {
      "recipient_status": "sent",
      "recipient_type": "signer",
      "email": "john.doe@example.com",
      "name": "John Doe"
    }
  ],
  "provider_type": "docusign",
  "envelope_id": "env_789xyz",
  "envelope_url": {
    "url_type": "view",
    "url": "https://app.docusign.com/..."
  },
  "signing_files": [
    {
      "file_id": 101,
      "file_type": "document",
      "file_name": "vendor_contract.pdf",
      "variable_id": "signing_document",
      "created_at": "2026-05-10T14:00:00Z"
    }
  ]
}

​
Response Fields

FieldTypeDescription
step_runobjectCurrent signature step run details
signature_statusstringEnvelope/signature status: created, sent, delivered, completed, declined, voided
coordinator_user_idinteger or nullID of the user coordinating the signature, if any
recipientsarray or nullRecipients on the envelope
provider_typestringSignature provider: docusign, self_sign, manual, chameliosign
envelope_idstring or nullProvider envelope identifier, if an envelope exists
envelope_urlobject or nullCoordinator envelope URL (only present when create_envelope_url=true and available)
signing_filesarrayFiles associated with the signature step (empty array if none)

​
Step Run Object Fields

FieldTypeDescription
step_run_idstringUnique identifier for this step run
step_idstringIdentifier for the step definition
step_namestringHuman-readable step name
step_typestringType of workflow component (e.g., "signature")
statusstringStep run status: initiated, pending, in_progress, completed, failed, rejected, cancelled
variablesarrayVariables associated with this step run

​
Variable Object Fields

FieldTypeDescription
variable_typestringType of the variable: text, number, boolean, date, email, file, select, multi_select, user_entity, business, dynamic_list, dynamic_table, number_with_currency, conversation
valueanyCurrent value of the variable (string, number, boolean, array, or null)
step_idstringID of the step that collected this variable
variable_idstringUnique identifier for the variable

​
Recipient Object Fields

FieldTypeDescription
recipient_statusstringRecipient status: created, sent, delivered, completed, declined
recipient_typestringRecipient role: signer or viewer
emailstring or nullRecipient email address
namestring or nullRecipient name

​
Envelope URL Object Fields

FieldTypeDescription
url_typestringType of URL: edit or view
urlstringCoordinator envelope URL

​
Signing File Object Fields

FieldTypeDescription
file_idintegerInternal identifier for the file
file_typestringType of file: document or attachment
file_namestringOriginal filename
variable_idstring or nullWorkflow variable ID this file is bound to, if any
created_atstringISO 8601 timestamp when the file was created

​
Error Responses

​
401 Unauthorized

Returned when authentication fails. See the authentication errors section for details. 
{
  "detail": "Invalid API key"
}

​
404 Not Found

Returned when the task doesn’t exist or you don’t have access to it. 
{
  "detail": "Task not found"
}

​
409 Conflict

Returned when the task is not currently at a signature step. 
{
  "detail": "Task is not at a signature step"
}

​
422 Validation Error

Returned when request parameters are invalid. 
{
  "detail": [
    {
      "loc": ["path", "task_id"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

​
500 Internal Server Error

Returned when the request fails due to a server error. 
{
  "detail": "Failed to get signature details"
}

​
Notes

Call this endpoint before Initiate Signature to read the current step status and existing recipients, and to obtain the step_run_id you need to initiate signing.
The envelope_url is only returned when you set create_envelope_url=true and an envelope URL is available from the provider.

​
Use Cases

This endpoint is useful for:
  • Signature status tracking - Monitor envelope and per-recipient signing progress
  • Custom signing UIs - Build interfaces that display recipients, provider, and envelope links
  • Pre-initiation inspection - Inspect the signature step and recipients before initiating or modifying signing
  • Provider awareness - Adapt behavior based on the signature provider in use