[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# Documents

List reusable document templates, send them to contacts for review or e-signature, and inspect signature request status.

## The Document Object

Generated from the OpenAPI schema. Always matches the live API.

**Fields (10)**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | integer | - | Document id. |  |
| `tag` | string | - | Document tag. |  |
| `name` | string | - | Document name. |  |
| `description` | string | - | Document description. |  |
| `file` | object | - | The stored file. |  |
| `file.id` | string | - | File id. |  |
| `file.name` | string | - | File name. |  |
| `file.size` | integer or null | - | File size in bytes, or null. |  |
| `request` | string | - | Whether/how a signature can be requested for this document. |  |
| `updated` | integer | - | Unix timestamp the document was last updated. |  |

**Example object**

```json
{
    "id": 0,
    "tag": "",
    "name": "",
    "description": "",
    "file": {
        "id": "",
        "name": "",
        "size": 0
    },
    "request": "",
    "updated": 0
}
```

## Endpoints

### GET List Documents

`GET /2.0/documents` · scope `documents:read`

List documents with pagination and optional filters.

**Parameters (6)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | - | Page number, starting at 1 (offset pagination). |  |
| `per_page` | query | integer | - | Results per page (maximum 500). |  |
| `tag` | query | string | - | Filter by tag. Supports wildcards (%) with the search:wildcard scope. |  |
| `updated` | query | string | - | Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. |  |
| `cursor` | query | string | - | Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Paginated documents |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": [
        {
            "id": 0,
            "tag": "",
            "name": "",
            "description": "",
            "file": {
                "id": "",
                "name": "",
                "size": 0
            },
            "request": "",
            "updated": 0
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}
```

### GET Get Document

`GET /2.0/documents/{id}` · scope `documents:read`

Retrieve a single document by id.

**Parameters (2)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Document |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 0,
        "tag": "",
        "name": "",
        "description": "",
        "file": {
            "id": "",
            "name": "",
            "size": 0
        },
        "request": "",
        "updated": 0
    }
}
```

### Send

### POST Send Documents

`POST /2.0/documents/send` · scope `documents:send`

Send one or more documents to a contact for review or e-signing. Optionally set a redirect to return the contact to an invoice, order, or purchase after signing completes.

**Request body**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `contact` | integer | Yes | Contact id to send the documents to. | `77684` |
| `documents` | array of string | Yes | Documents to send. Each item is a document id, a document tag, or a {id, tag} object. | `[12]` |
| `esign` | boolean | - | Whether the documents require e-signature (true) or are sent for review only (false). | `true` |
| `redirect` | object | - | Optional: after signing, return the contact to an existing invoice/order/purchase for the same contact (sets the post-signing redirect URL and label). |  |
| `redirect.type` | enum | Yes | The kind of record to return to. | `invoice` |
| `redirect.id` | integer | Yes | The invoice/order/purchase id to return to. | `11492` |

```json
{
    "contact": 77684,
    "documents": [
        12
    ],
    "esign": true,
    "redirect": {
        "type": "invoice",
        "id": 11492
    }
}
```

**Responses**

| Status | Description |
| --- | --- |
| `201` Created | Document signature request created and sent |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 0,
        "code": "",
        "contact": 0,
        "customer_name": "",
        "esign": false,
        "signed": false,
        "signed_at": 0,
        "requested": 0,
        "documents": [
            {
                "tag": "",
                "name": "",
                "signed": false,
                "signed_at": 0
            }
        ],
        "url": ""
    }
}
```

### Signatures

### GET List Signature Requests

`GET /2.0/documents/signatures` · scope `document-signatures:read`

List document signature requests.

**Parameters (6)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | - | Page number, starting at 1 (offset pagination). |  |
| `per_page` | query | integer | - | Results per page (maximum 500). |  |
| `contact` | query | integer | - | Filter by contact id. |  |
| `signed` | query | integer | - | Filter by signed state: 0 (unsigned) or 1 (signed). |  |
| `cursor` | query | string | - | Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Paginated document signature requests |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": [
        {
            "id": 0,
            "code": "",
            "contact": 0,
            "customer_name": "",
            "esign": false,
            "signed": false,
            "signed_at": 0,
            "requested": 0,
            "documents": [
                {
                    "tag": "",
                    "name": "",
                    "signed": false,
                    "signed_at": 0
                }
            ],
            "url": ""
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}
```

### GET Get Signature Request

`GET /2.0/documents/signatures/{signature_id}` · scope `document-signatures:read`

Retrieve a single document signature request by id.

**Parameters (2)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `signature_id` | path | string | Yes | Resource identifier in the path. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Document signature request |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 0,
        "code": "",
        "contact": 0,
        "customer_name": "",
        "esign": false,
        "signed": false,
        "signed_at": 0,
        "requested": 0,
        "documents": [
            {
                "tag": "",
                "name": "",
                "signed": false,
                "signed_at": 0
            }
        ],
        "url": ""
    }
}
```