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

> Retrieve every signed document associated with a workflow task in Chamelio Flows using an OAuth access token, including any signature certificates.

## Endpoint

```
GET /v2/tasks/{task_id}/signed-documents
```

## Authentication

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

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `files:read`

> [!NOTE]
>
> This endpoint hangs off `/tasks` but is gated on `files:read`, not `tasks:read`, because it returns
> documents. A token with only `tasks:read` gets a `403`.

## Path Parameters

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

## Request Example

```bash cURL theme={null}
curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/signed-documents" \
  -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}/signed-documents"
headers = {
    "Authorization": "Bearer your_access_token"
}

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

```javascript JavaScript theme={null}
const taskId = 12345;

const response = await fetch(
  `https://platform.chamelio.ai/v2/tasks/${taskId}/signed-documents`,
  {
    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}
{
  "task_id": 12345,
  "workflow_status": "completed",
  "total": 2,
  "documents": [
    {
      "file_id": "document_789",
      "file_name": "signed_contract.pdf",
      "step_id": "sign_step_1",
      "step_name": "Executive Signature",
      "sor_document_id": 4821,
      "download_url": "https://s3.amazonaws.com/chamelio-files/...",
      "expires_at": "2025-01-20T12:00:00Z"
    },
    {
      "file_id": "document_790",
      "file_name": "signed_nda.pdf",
      "step_id": "sign_step_2",
      "step_name": "NDA Signature",
      "sor_document_id": null,
      "download_url": "https://s3.amazonaws.com/chamelio-files/...",
      "expires_at": "2025-01-20T12:00:00Z"
    }
  ]
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `task_id` | integer | ID of the task |
| `workflow_status` | string | Current status of the workflow |
| `total` | integer | Total number of signed documents |
| `documents` | array | List of signed documents associated with the task |

### Document Object Fields

| Field | Type | Description |
| - | - | - |
| `file_id` | string | Unique identifier of the signed document |
| `file_name` | string | Name of the signed document file |
| `step_id` | string | ID of the workflow step that produced this signed document |
| `step_name` | string | Display name of the workflow step |
| `sor_document_id` | integer or null | Document repository (Core) ID of the signed document. `null` until the signed document has been stored and processed |
| `download_url` | string | Presigned URL to download the signed document |
| `expires_at` | string | ISO 8601 timestamp when the download URL expires |

## 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: files: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"
}
```

### 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 signed documents"
}
```

## Notes

> [!NOTE]
>
> This endpoint returns signed documents from all signature steps within the task. The `total` field
> reflects the count of documents in the response.

> [!NOTE]
>
> Signed documents are only available for tasks with status `completed`.

> [!WARNING]
>
> Presigned download URLs expire after a certain time (indicated by `expires_at` on each document).
> Download the files before the URLs expire or request new URLs.

> [!TIP]
>
> Use the `step_name` field to identify which signature step each document belongs to, especially when a
> workflow contains multiple signing steps.

## Use Cases

This endpoint is useful for:

* **Post-signing retrieval** - Download fully executed contracts after all parties have signed
* **Document archival** - Save signed documents to long-term storage or a contract management system
* **Audit trails** - Verify which documents were signed as part of a workflow
* **Integration** - Sync signed contracts with ERP, CRM, or document management platforms
