Get Signature Details

Endpoint

GET /v2/tasks/{task_id}/signature-details

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: tasks:read

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/v2/tasks/12345/signature-details?create_envelope_url=true" \
  -H "Authorization: Bearer your_access_token"

import requests

task_id = 12345

url = f"https://platform.chamelio.ai/v2/tasks/{task_id}/signature-details"
headers = {
    "Authorization": "Bearer your_access_token"
}
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/v2/tasks/${taskId}/signature-details?create_envelope_url=true`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_access_token'
    }
  }
);

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`, `multiple_files`, `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 of strings, or null)
`step_id`	string	ID of the step that collected this variable
`variable_id`	string	Unique identifier for the variable
`variable_title`	string or null	Human-readable variable name

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

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token lacks the required scope:

{
  "detail": "Insufficient scope; this endpoint requires: tasks:read"
}

Or when the user may not access this task:

{
  "detail": "You do not have access to this resource"
}

404 Not Found

Returned when the task does not exist.

{
  "detail": "Not found"
}

409 Conflict

Returned when the task is not currently at a signature step.

{
  "detail": "The task is not in a state that allows this operation"
}

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"
    }
  ]
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

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 previous_negotiation_step_run_id to fetch the negotiation history that led to the document being signed, via Get Latest Negotiation Versions.

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 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

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

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

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​422 Validation Error

​429 Too Many Requests

​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

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases