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

# Exporting a comparison to PDF

> How to turn a completed Draftable API comparison into a downloadable PDF, including the four export kinds and how to retrieve the finished file.

The viewer is interactive, but sometimes you need a file: something to attach to an email, file against a matter, or send to someone who will not open a link.

The exports endpoint turns a completed comparison into a downloadable PDF.

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

<Note>
  You can only export a comparison that has finished processing. Confirm `ready` is `true` and `failed` is `false` before creating an export.
</Note>

## Export kinds

Choose what the PDF should contain with the `kind` parameter.

| Kind          | What the PDF contains                                                                       |
| :------------ | :------------------------------------------------------------------------------------------ |
| `single_page` | The right (revised) document only, with highlights and deletion markers showing the changes |
| `combined`    | Both documents, left and right                                                              |
| `left`        | The left (original) document only                                                           |
| `right`       | The right (revised) document only                                                           |

<Tip>
  `single_page` is the one most people want. It reads as a single reviewable document, in the way a redline does, rather than as two documents side by side. Use `combined` when the reader needs to see both versions in full.
</Tip>

## Creating an export

```bash theme={null}
curl -X POST https://api.draftable.com/v1/exports \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -F "comparison=aBcDeFgH" \
  -F "kind=single_page"
```

| Parameter            | Required | Description                                                                    |
| :------------------- | :------: | :----------------------------------------------------------------------------- |
| `comparison`         |    Yes   | The identifier of the comparison to export                                     |
| `kind`               |    Yes   | One of the four kinds above                                                    |
| `include_cover_page` |    No    | Whether a cover page is included for the `combined` export. Defaults to `true` |

The response is **201 Created**:

```json theme={null}
{
  "identifier": "xYzExPoRt",
  "comparison": "aBcDeFgH",
  "kind": "single_page",
  "ready": false,
  "failed": false
}
```

As with comparisons, exports are generated asynchronously. The response comes back immediately with `ready: false` and no `url`.

## Retrieving the finished PDF

Poll the export until it is ready:

```
GET https://api.draftable.com/v1/exports/{identifier}
```

```bash theme={null}
curl https://api.draftable.com/v1/exports/xYzExPoRt \
  -H "Authorization: Token YOUR_AUTH_TOKEN"
```

When it completes, a `url` appears:

```json theme={null}
{
  "identifier": "xYzExPoRt",
  "comparison": "aBcDeFgH",
  "kind": "single_page",
  "url": "https://...",
  "ready": true,
  "failed": false
}
```

Download the PDF from that URL.

<Warning>
  The download URL is **signed and time-limited**. Fetch the file promptly rather than storing the URL for later use. If a stored URL has expired, create a new export to get a fresh one.
</Warning>

As with comparisons, `ready: true` means processing finished, not that it succeeded. Check `failed`, and read `error_message` when it is `true`.

## A complete flow

<Steps>
  <Step title="Create the comparison">
    `POST /comparisons` with both documents. Keep the returned identifier.
  </Step>

  <Step title="Wait for the comparison to be ready">
    Poll `GET /comparisons/{identifier}` until `ready` is `true`. Confirm `failed` is `false`.
  </Step>

  <Step title="Create the export">
    `POST /exports` with the comparison identifier and your chosen kind.
  </Step>

  <Step title="Wait for the export to be ready">
    Poll `GET /exports/{identifier}` until `ready` is `true`.
  </Step>

  <Step title="Download the file">
    Fetch the PDF from the `url` in the response, promptly.
  </Step>
</Steps>

Note the two separate waits. A common mistake is creating an export immediately after creating a comparison, before the comparison itself has finished.

## Related articles

<CardGroup>
  <Card title="Creating a comparison" icon="file-import" href="/hc/en-us/articles/Draftable-API-creating-a-comparison" iconType="solid" horizontal />

  <Card title="Viewing and sharing results" icon="eye" href="/hc/en-us/articles/Draftable-API-viewing-and-sharing-results" 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>