Viewing and sharing comparison results

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}

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`

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.

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

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.

Generating a signed URL

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

url = client.comparisons.signed_viewer_url(
    identifier,
    valid_until=timedelta(minutes=30),
)

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.

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.

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.

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.

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.

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.

Getting started

Using the API

Account & customization

Troubleshooting & status

Viewing and sharing comparison results

Knowing when a comparison is ready

Polling sensibly

Viewer URLs

Public comparisons

Private comparisons (the default)

Generating a signed URL

Choosing an expiry

Skipping the wait with `wait`

Getting results as data

Customising the viewer

Creating a comparison

Exporting a comparison to PDF

Results as JSON

Customizing your account and viewer

​Knowing when a comparison is ready

​Polling sensibly

​Viewer URLs

​Public comparisons

​Private comparisons (the default)

​Generating a signed URL

​Choosing an expiry

​Skipping the wait with wait

​Getting results as data

​Customising the viewer

​Related articles

Creating a comparison

Exporting a comparison to PDF

Results as JSON

Customizing your account and viewer

Knowing when a comparison is ready

Polling sensibly

Viewer URLs

Public comparisons

Private comparisons (the default)

Generating a signed URL

Choosing an expiry

Skipping the wait with `wait`

Getting results as data

Customising the viewer

Related articles