Getting started with the Draftable API

The Draftable API lets you compare two documents programmatically and present the result to your users, without building any comparison logic yourself. This article is the starting point. Work through it and you will have created your first comparison and viewed the result. The articles that follow go deeper into each step.

What the API does

You send Draftable two documents. Draftable compares them and produces an interactive Side-by-Side comparison that your users open in a browser, showing exactly what changed between the two versions. Supported file types are PDF, Word (.doc, .docx, .docm), PowerPoint (.ppt, .pptx, .pptm), RTF and plain text. You can compare across formats, so a Word document can be compared against a PDF.

How a comparison flows

Every integration follows the same four stages. Understanding this shape makes the rest of the API straightforward.

Create the comparison

You send both documents to Draftable, either as direct uploads or as URLs Draftable fetches for you. Draftable responds immediately with a comparison identifier.

Draftable processes it

Comparison happens asynchronously. Larger documents take longer.

You wait for it to be ready

You either poll the comparison until it reports as ready, or hand the user a viewer URL that waits for you.

You present the result

You give the user a viewer URL. Optionally, you also export the comparison to PDF.

Creating a comparison is fast and always returns straight away. It does not block while the documents are compared. Any integration you build needs to account for the comparison not being ready the instant you create it.

Before you start

You need an account ID and an auth token. Both are available from your account at api.draftable.com/account/credentials. You will see two sets: one labelled test and one labelled production. Use the test credentials while you are building. They behave identically to production credentials but keep your development traffic separate. See Test and production accounts for the detail.

Your first comparison

The API is available at:

https://api.draftable.com/v1

Authenticate by sending your auth token in an Authorization header.

Step 1: Create a comparison

The simplest way to start is with two documents Draftable can fetch by URL. Draftable hosts sample documents you can use for this.

curl -X POST https://api.draftable.com/v1/comparisons \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -F "left.source_url=https://api.draftable.com/static/test-documents/code-of-conduct/left.rtf" \
  -F "left.file_type=rtf" \
  -F "right.source_url=https://api.draftable.com/static/test-documents/code-of-conduct/right.pdf" \
  -F "right.file_type=pdf"

Draftable responds with the new comparison:

{
  "identifier": "aBcDeFgH",
  "left":  { "source_url": "...", "file_type": "rtf" },
  "right": { "source_url": "...", "file_type": "pdf" },
  "creation_time": "2026-09-02T09:15:00.000Z",
  "public": false,
  "ready": false
}

Note "ready": false. The comparison exists, but Draftable is still working on it. Keep the identifier, as everything else you do refers to it.

Step 2: Check whether it is ready

curl https://api.draftable.com/v1/comparisons/aBcDeFgH \
  -H "Authorization: Token YOUR_AUTH_TOKEN"

When processing finishes, ready becomes true and a ready_time appears. Check failed as well, because a comparison can finish unsuccessfully.

Step 3: View the result

Open the comparison in the viewer:

https://api.draftable.com/v1/viewer/YOUR_ACCOUNT_ID/aBcDeFgH

By default comparisons are private, so this URL requires a signature. Viewing and sharing comparison results explains how to generate one, and how to avoid polling entirely using the wait parameter.

Use a client library

Everything above is a plain REST call, so any HTTP client works. For most integrations the official client libraries are quicker, because they handle authentication, polling and viewer URL signing for you. Libraries are available for .NET, Node.js, Python and Java. See API client libraries. Here is the same comparison in Python:

import draftable

client = draftable.Client(ACCOUNT_ID, AUTH_TOKEN)
comparisons = client.comparisons

comparison = comparisons.create(
    left=draftable.make_side("https://api.draftable.com/static/test-documents/code-of-conduct/left.rtf", file_type="rtf"),
    right=draftable.make_side("https://api.draftable.com/static/test-documents/code-of-conduct/right.pdf", file_type="pdf"),
)

print(comparisons.signed_viewer_url(comparison.identifier))

Getting started

Using the API

Account & customization

Troubleshooting & status

Getting started with the Draftable API

What the API does

How a comparison flows

Before you start

Your first comparison

Step 1: Create a comparison

Step 2: Check whether it is ready

Step 3: View the result

Use a client library

Where to go next

Authenticating with the Draftable API

Test and production accounts

Creating a comparison

Viewing and sharing results

Exporting a comparison to PDF

Handling errors and failures

​What the API does

​How a comparison flows

​Before you start

​Your first comparison

​Step 1: Create a comparison

​Step 2: Check whether it is ready

​Step 3: View the result

​Use a client library

​Where to go next

Authenticating with the Draftable API

Test and production accounts

Creating a comparison

Viewing and sharing results

Exporting a comparison to PDF

Handling errors and failures

What the API does

How a comparison flows

Before you start

Your first comparison

Step 1: Create a comparison

Step 2: Check whether it is ready

Step 3: View the result

Use a client library

Where to go next