> ## 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. Identifiers must be unique within your account.

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