> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Signature Details
> Retrieve signature step status, recipients, provider, and envelope details for a task
## Endpoint
```
GET /v2/tasks/{task_id}/signature-details
```
## Authentication
This endpoint requires an OAuth access token. Send it as a bearer token:
```bash theme={null}
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
```bash cURL theme={null}
curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/signature-details?create_envelope_url=true" \
-H "Authorization: Bearer your_access_token"
```
```python Python theme={null}
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())
```
```javascript JavaScript theme={null}
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`
```json theme={null}
{
"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.
```json theme={null}
{
"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](/api-reference/oauth-apps#error-responses).
```json theme={null}
{
"detail": "Invalid access token"
}
```
### 403 Forbidden
Returned when the token lacks the required scope:
```json theme={null}
{
"detail": "Insufficient scope; this endpoint requires: tasks:read"
}
```
Or when the user may not access this task:
```json theme={null}
{
"detail": "You do not have access to this resource"
}
```
### 404 Not Found
Returned when the task does not exist.
```json theme={null}
{
"detail": "Not found"
}
```
### 409 Conflict
Returned when the task is not currently at a signature step.
```json theme={null}
{
"detail": "The task is not in a state that allows this operation"
}
```
### 422 Validation Error
Returned when request parameters are invalid.
```json theme={null}
{
"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.
```json theme={null}
{
"detail": "Rate limit exceeded"
}
```
### 500 Internal Server Error
Returned when the request fails due to a server error.
```json theme={null}
{
"detail": "Failed to get signature details"
}
```
## Notes
Call this endpoint before [Initiate Signature](/api-reference/endpoint/v2/tasks/initiate-sign) 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](/api-reference/endpoint/v2/tasks/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