> ## Documentation Index
> Fetch the complete documentation index at: https://help.draftable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a comparison with the Draftable API

> A full reference for creating comparisons: uploading files versus supplying URLs, supported file types, identifiers, expiry, and public comparisons.

Creating a comparison is the one request every Draftable API integration makes. This article covers it in full.

```
POST https://api.draftable.com/v1/comparisons
```

The request is `multipart/form-data`. It returns immediately with a comparison object; processing continues in the background.

## Supplying the two documents

Every comparison has a **left** side (the original) and a **right** side (the revised version). Changes are described relative to the left.

For each side you must provide the file itself and its type. There are two ways to supply a file, and you must choose exactly one per side.

### Option A: upload the file directly

Use this when the document is on your server or was just uploaded by a user.

```bash theme={null}
curl -X POST https://api.draftable.com/v1/comparisons \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -F "left.file=@contract-v1.docx" \
  -F "left.file_type=docx" \
  -F "right.file=@contract-v2.docx" \
  -F "right.file_type=docx"
```

### Option B: give Draftable a URL to fetch

Use this when the documents are already reachable at a URL. Draftable fetches them itself.

```bash theme={null}
curl -X POST https://api.draftable.com/v1/comparisons \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -F "left.source_url=https://example.com/contract-v1.docx" \
  -F "left.file_type=docx" \
  -F "right.source_url=https://example.com/contract-v2.docx" \
  -F "right.file_type=docx"
```

<Warning>
  For each side, supply **either** `file` **or** `source_url`, never both. Supplying both is rejected as a malformed request.
</Warning>

<Note>
  A `source_url` must be reachable by Draftable from the public internet. A URL on your internal network, behind a VPN, or requiring authentication will fail. If your documents are not publicly reachable, upload them directly instead.
</Note>

You can mix the two approaches across sides. Uploading the left file while supplying a URL for the right is perfectly valid.

## Parameters

| Parameter            | Required | Description                                                                   |
| :------------------- | :------: | :---------------------------------------------------------------------------- |
| `left.file`          |  One of  | The left file, as bytes                                                       |
| `left.source_url`    |  One of  | A URL Draftable fetches the left file from                                    |
| `left.file_type`     |    Yes   | The left file's type                                                          |
| `left.display_name`  |    No    | The name shown for the left file in the viewer                                |
| `right.file`         |  One of  | The right file, as bytes                                                      |
| `right.source_url`   |  One of  | A URL Draftable fetches the right file from                                   |
| `right.file_type`    |    Yes   | The right file's type                                                         |
| `right.display_name` |    No    | The name shown for the right file in the viewer                               |
| `identifier`         |    No    | Your own identifier for the comparison                                        |
| `public`             |    No    | Whether the comparison can be viewed without a signature. Defaults to `false` |
| `expiry_time`        |    No    | When the comparison is automatically deleted. Defaults to no expiry           |

### File types

`file_type` is **required** on both sides and must be given explicitly. Draftable does not infer it from the file name or content.

| Category   | Accepted values       |
| :--------- | :-------------------- |
| PDF        | `pdf`                 |
| Word       | `doc`, `docx`, `docm` |
| PowerPoint | `ppt`, `pptx`, `pptm` |
| Rich text  | `rtf`                 |
| Plain text | `txt`                 |

The two sides do not have to match. Comparing a `docx` against a `pdf` is fully supported and common.

<Tip>
  When comparing a Word file against a PDF, expect some formatting differences to be reported that a Word-to-Word comparison would not show. The two formats describe layout differently, so converting both sides to the same format before submitting usually gives a cleaner result.
</Tip>

### Display names

`display_name` controls the label shown above each document in the viewer. Without it, the viewer falls back to a generic label, which is rarely what your users want to see.

```bash theme={null}
-F "left.display_name=Contract (original)" \
-F "right.display_name=Contract (amended 2 Sept)"
```

### Identifiers

By default Draftable generates an identifier and returns it. You can supply your own instead:

```bash theme={null}
-F "identifier=matter-4471-contract-rev3"
```

This is useful when you want to build the viewer URL before the comparison finishes, or map comparisons onto records in your own system.

Custom identifiers have three rules:

| Rule                   | Detail                                                                                         |
| :--------------------- | :--------------------------------------------------------------------------------------------- |
| **Allowed characters** | Letters and digits (`a-z`, `A-Z`, `0-9`) plus hyphen, underscore and full stop (`-`, `_`, `.`) |
| **Length**             | Between 1 and 1024 characters                                                                  |
| **Uniqueness**         | Must not match an existing comparison                                                          |

Reusing an existing identifier returns **400 Bad Request** and the comparison is not created.

<Note>
  Once a comparison is **deleted**, its identifier becomes available again. This is useful if you key comparisons off a record in your own system and need to regenerate one.
</Note>

<Tip>
  Supplying your own identifier lets you construct the viewer URL **before** the comparison exists, so you can create comparisons in a background job and hand users a link immediately. Pair it with the `wait` parameter, or the viewer returns 404 until the comparison is created. See [Viewing and sharing comparison results](/hc/en-us/articles/Draftable-API-viewing-and-sharing-results).
</Tip>

### Expiry

`expiry_time` sets when Draftable automatically deletes the comparison and its documents. It takes an ISO 8601 timestamp:

```bash theme={null}
-F "expiry_time=2026-09-30T23:59:59Z"
```

With no expiry set, the comparison is retained until you delete it.

<Tip>
  Setting an expiry on every comparison is good practice. It bounds how long your documents are stored, and means you do not need a separate cleanup process. You can also delete comparisons explicitly at any time.
</Tip>

### Public comparisons

`public` controls whether the comparison can be viewed without a signature.

* **`false` (default)** — the comparison is private and its viewer URL must be signed. This is the right choice for anything confidential.
* **`true`** — anyone with the viewer URL can open it, with no signature and no expiry on access.

<Warning>
  Only set `public=true` for content you are content to have accessible to anyone who obtains the URL. A public comparison URL is not guessable, but it is not protected either.
</Warning>

## The response

A successful request returns **201 Created**:

```json theme={null}
{
  "identifier": "aBcDeFgH",
  "left": {
    "source_url": "https://example.com/contract-v1.docx",
    "display_name": "Contract (original)",
    "file_type": "docx"
  },
  "right": {
    "source_url": "https://example.com/contract-v2.docx",
    "display_name": "Contract (amended 2 Sept)",
    "file_type": "docx"
  },
  "creation_time": "2026-09-02T09:15:00.000Z",
  "expiry_time": "2026-09-30T23:59:59.000Z",
  "public": false,
  "ready": false
}
```

`ready` is `false` because comparison happens asynchronously. See [Viewing and sharing comparison results](/hc/en-us/articles/Draftable-API-viewing-and-sharing-results) for what to do next.

A malformed request returns **400 Bad Request**. See [Handling errors and comparison failures](/hc/en-us/articles/Draftable-API-handling-errors).

## Limits

Each account has a limit on the size and length of files it can submit, by default around **40 MB** and **1,000 pages** per file. Files above the limit are rejected.

If your documents are larger, contact **[support@draftable.com](mailto:support@draftable.com)** and we will review your use case. See [Customizing your account and viewer](/hc/en-us/articles/Customizing-your-Draftable-API-account-and-viewer).

## Listing comparisons

To retrieve the comparisons on your account:

```
GET https://api.draftable.com/v1/comparisons
```

Results are limited to **300 per page**. Use `limit` and `offset` to page through them. The response includes a `count` of the total.

Only comparisons created with the credential set you authenticate with are returned.

## Related articles

<CardGroup>
  <Card title="Viewing and sharing results" icon="eye" href="/hc/en-us/articles/Draftable-API-viewing-and-sharing-results" iconType="solid" horizontal />

  <Card title="Exporting a comparison to PDF" icon="file-pdf" href="/hc/en-us/articles/Draftable-API-exporting-comparisons" iconType="solid" horizontal />

  <Card title="How to delete comparisons" icon="trash" href="/hc/en-us/articles/How-to-delete-comparisons-in-Draftable-API" iconType="solid" horizontal />

  <Card title="Handling errors and failures" icon="triangle-exclamation" href="/hc/en-us/articles/Draftable-API-handling-errors" iconType="solid" horizontal />
</CardGroup>