Get Signature Details

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

Parameter	Type	Required	Description
`task_id`	integer	Yes	Unique identifier for the task

Query Parameters

Parameter	Type	Required	Description
`create_envelope_url`	boolean	No	Include 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"
    }
  ],
  "previous_negotiation_step_run_id": "sr_neg_001"
}

Response Fields

Field	Type	Description
`step_run`	object	Current signature step run details
`signature_status`	string	Envelope/signature status: `created`, `sent`, `delivered`, `completed`, `declined`, `voided`
`coordinator_user_id`	integer or null	ID of the user coordinating the signature, if any
`recipients`	array or null	Recipients on the envelope
`provider_type`	string	Signature provider: `docusign`, `self_sign`, `manual`, `chameliosign`
`envelope_id`	string or null	Provider envelope identifier, if an envelope exists
`envelope_url`	object or null	Coordinator envelope URL (only present when `create_envelope_url=true` and available)
`signing_files`	array	Files associated with the signature step (empty array if none)
`previous_negotiation_step_run_id`	string or null	Step run ID of the negotiation step that preceded this signature step, if any

Step Run Object Fields

Field	Type	Description
`step_run_id`	string	Unique identifier for this step run
`step_id`	string	Identifier for the step definition
`step_name`	string	Human-readable step name
`step_type`	string	Type of workflow component (e.g., `"signature"`)
`status`	string	Step run status: `initiated`, `pending`, `in_progress`, `completed`, `failed`, `rejected`, `cancelled`
`variables`	array	Variables associated with this step run

Variable Object Fields

Field	Type	Description
`variable_type`	string	Type of the variable: `text`, `number`, `boolean`, `date`, `email`, `file`, `select`, `multi_select`, `user_entity`, `business`, `dynamic_list`, `dynamic_table`, `number_with_currency`, `conversation`
`value`	any	Current value of the variable (string, number, boolean, array, or null)
`step_id`	string	ID of the step that collected this variable
`variable_id`	string	Unique identifier for the variable

Recipient Object Fields

Field	Type	Description
`recipient_status`	string	Recipient status: `created`, `sent`, `delivered`, `completed`, `declined`
`recipient_type`	string	Recipient role: `signer` or `viewer`
`email`	string or null	Recipient email address
`name`	string or null	Recipient name

Envelope URL Object Fields

Field	Type	Description
`url_type`	string	Type of URL: `edit` or `view`
`url`	string	Coordinator envelope URL

Signing File Object Fields

Field	Type	Description
`file_id`	integer	Internal identifier for the file
`file_type`	string	Type of file: `document` or `attachment`
`file_name`	string	Original filename
`variable_id`	string or null	Workflow variable ID this file is bound to, if any
`created_at`	string	ISO 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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

Step Run Object Fields

Variable Object Fields

Recipient Object Fields

Envelope URL Object Fields

Signing File Object Fields

Error Responses

401 Unauthorized

404 Not Found

409 Conflict

422 Validation Error

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Request Example

​Response

​Success Response

​Response Fields

​Step Run Object Fields

​Variable Object Fields

​Recipient Object Fields

​Envelope URL Object Fields

​Signing File Object Fields

​Error Responses

​401 Unauthorized

​404 Not Found

​409 Conflict

​422 Validation Error

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

Step Run Object Fields

Variable Object Fields

Recipient Object Fields

Envelope URL Object Fields

Signing File Object Fields

Error Responses

401 Unauthorized

404 Not Found

409 Conflict

422 Validation Error

500 Internal Server Error

Notes

Use Cases