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

# Viewing and sharing comparison results

> How to know when a comparison is ready, how to build public and signed viewer URLs, and how the wait parameter removes the need to poll.

Once you have created a comparison, two things remain: knowing when it is ready, and getting it in front of a user.

## Knowing when a comparison is ready

Comparison is asynchronous, so a newly created comparison is not immediately viewable. Fetch it to check:

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

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

The fields that matter:

| Field           | Meaning                                                                    |
| :-------------- | :------------------------------------------------------------------------- |
| `ready`         | Processing has finished. Check this first                                  |
| `ready_time`    | When it finished                                                           |
| `failed`        | Only meaningful once `ready` is `true`. Whether it finished unsuccessfully |
| `error_message` | Present when `failed` is `true`                                            |

<Warning>
  `ready: true` does **not** mean success. It means processing finished. Always check `failed` as well. A comparison that failed is ready, and has an `error_message` explaining why.
</Warning>

### Polling sensibly

If you poll, back off rather than hammering the endpoint. Most comparisons complete in seconds, but a large document takes longer.

A reasonable pattern is to check after one second, then at growing intervals, with an overall timeout after which you surface an error to the user.

Better still, avoid polling altogether using the `wait` parameter described below.

## Viewer URLs

The viewer is where your users actually see the comparison. Viewer URLs are built from your **account ID** and the **comparison identifier**:

```
https://api.draftable.com/v1/viewer/{account_id}/{identifier}
```

How you use that URL depends on whether the comparison is public or private.

### Public comparisons

If you created the comparison with `public=true`, the URL above works as-is. Anyone holding it can open the comparison.

```
https://api.draftable.com/v1/viewer/aBcDeFgH/matter-4471-contract-rev3
```

### Private comparisons (the default)

Private comparisons require a **signed URL**. The signature proves the URL was issued by you, and it carries an expiry, so access is time-limited.

A signed URL adds two query parameters:

```
https://api.draftable.com/v1/viewer/{account_id}/{identifier}?valid_until={timestamp}&signature={signature}
```

| Parameter     | Description                                                                                                                                    |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `valid_until` | A Unix timestamp after which the link stops working                                                                                            |
| `signature`   | An HMAC-SHA256 signature, hex encoded, computed over the account ID, identifier and `valid_until`, using your **auth token** as the secret key |

<Note>
  This is the intended way to show a comparison to an end user. The user gets time-limited access to one specific comparison and never sees your auth token.
</Note>

### Generating a signed URL

The client libraries do this for you, and using them is strongly recommended over implementing the signature yourself:

```python theme={null}
url = client.comparisons.signed_viewer_url(
    identifier,
    valid_until=timedelta(minutes=30),
)
```

```javascript theme={null}
const url = client.signedViewerURL(identifier, 30 * 60, false);
```

If you must implement it manually, compute an HMAC-SHA256 over the account ID, comparison identifier and `valid_until` timestamp, keyed with your auth token, and hex encode the result. Getting this wrong produces a link the viewer rejects as invalid.

<Warning>
  Because the auth token is the signing key, **resetting your auth token invalidates every signed URL you have already issued**. Plan for this if you rotate tokens.
</Warning>

### Choosing an expiry

Keep `valid_until` as short as your workflow allows. The client libraries default to **30 minutes**, which suits the common case of generating a link at the moment a user clicks through to view a comparison.

Longer expiries are appropriate when you are emailing a link that someone may open later, but the longer the window, the longer a forwarded link keeps working.

## Skipping the wait with `wait`

Rather than polling until a comparison is ready and only then handing over a URL, you can add `wait` to the viewer URL:

```
https://api.draftable.com/v1/viewer/{account_id}/{identifier}?wait
```

The viewer then displays a loading state and shows the comparison as soon as it is ready.

Combined with a supplied `identifier`, this means you can construct the viewer URL and redirect a user to it **immediately after creating the comparison**, with no polling logic at all.

<Tip>
  This is the simplest possible integration. Create the comparison with your own identifier, build the signed viewer URL with `wait`, and redirect. The user sees a loading state and then the result.
</Tip>

When combining `wait` with a signature, it is appended alongside the other parameters:

```
?valid_until={timestamp}&signature={signature}&wait
```

## Getting results as data

If you need the changes as structured data rather than a viewer, for example to drive your own interface or run analysis, use the change details endpoint. See [Getting comparison results as JSON](/hc/en-us/articles/37873922031129-Getting-Comparison-Results-as-a-JSON-via-the-Change-Details-Endpoint-API).

## Customising the viewer

The viewer's appearance and controls can be tailored to your organisation, including colours, which controls appear, and white labelling. These are account-level settings applied by the Draftable team. See [Customizing your account and viewer](/hc/en-us/articles/Customizing-your-Draftable-API-account-and-viewer).

## 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="Exporting a comparison to PDF" icon="file-pdf" href="/hc/en-us/articles/Draftable-API-exporting-comparisons" iconType="solid" horizontal />

  <Card title="Results as JSON" icon="code" href="/hc/en-us/articles/37873922031129-Getting-Comparison-Results-as-a-JSON-via-the-Change-Details-Endpoint-API" iconType="solid" horizontal />

  <Card title="Customizing your account and viewer" icon="sliders" href="/hc/en-us/articles/Customizing-your-Draftable-API-account-and-viewer" iconType="solid" horizontal />
</CardGroup>