> ## 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`, `reference_file`, `reference_vault_item`, `formula` |
| `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](https://docs.chamelio.ai/api-reference/oauth-apps.md#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

> [!TIP]
>
> Call this endpoint before [Initiate Signature](https://docs.chamelio.ai/api-reference/endpoint/v2/tasks/initiate-sign.md) to read
> the current step status and existing recipients, and to obtain the `step_run_id` you need to initiate
> signing.

> [!NOTE]
>
> The `envelope_url` is only returned when you set `create_envelope_url=true` and an envelope URL is
> available from the provider.

> [!NOTE]
>
> Use `previous_negotiation_step_run_id` to fetch the negotiation history that led to the document being
> signed, via
> [Get Latest Negotiation Versions](https://docs.chamelio.ai/api-reference/endpoint/v2/tasks/latest-negotiation-versions.md).

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