Skip to main content
Creating a comparison is the one request every Draftable API integration makes. This article covers it in full.
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.

​
Option B: give Draftable a URL to fetch

Use this when the documents are already reachable at a URL. Draftable fetches them itself.
For each side, supply either file or source_url, never both. Supplying both is rejected as a malformed request.
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.
You can mix the two approaches across sides. Uploading the left file while supplying a URL for the right is perfectly valid.

​
Parameters

​
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. The two sides do not have to match. Comparing a docx against a pdf is fully supported and common.
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.

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

​
Identifiers

By default Draftable generates an identifier and returns it. You can supply your own instead:
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:
With no expiry set, the comparison is retained until you delete it.
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.

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

​
The response

A successful request returns 201 Created:
ready is false because comparison happens asynchronously. See Viewing and sharing comparison results for what to do next. A malformed request returns 400 Bad Request. See Handling errors and comparison failures.

​
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 and we will review your use case. See Customizing your account and viewer.

​
Listing comparisons

To retrieve the comparisons on your account:
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.

Viewing and sharing results

Exporting a comparison to PDF

How to delete comparisons

Handling errors and failures