Skip to main content
There are two ways to give Draftable the documents you want compared, and the choice has real consequences for performance, reliability and how much data moves through your own servers.
For each side, supply exactly one of the two. Sending both file and source_url for the same side is rejected as a malformed request, as is sending neither.
You can mix methods across sides. Uploading the left file while giving a URL for the right is perfectly valid.

​
Method 1: direct upload

Send the file’s bytes as part of a multipart/form-data request. Use this when the document is on your server, was just uploaded by a user, or is generated on the fly and does not exist at any URL.
The client libraries accept a file path or an open file object, so you can stream a file without loading it into memory:
Upside: it always works. There is nothing for Draftable to reach, so firewalls, private networks and authentication are irrelevant. Downside: the bytes travel twice, once from wherever they live to your server, then from your server to Draftable. For large files that is time and bandwidth you may not need to spend.
Because a large upload takes time, this is a good case for creating comparisons in a background job. Choose your own identifier, hand the user a viewer URL with wait immediately, and let the upload finish behind the scenes.

​
Method 2: source URL

Give Draftable a URL and it downloads the file directly.

​
Requirements

The URL must be reachable by Draftable, from the public internet, without authentication.
A URL that works in your browser is not necessarily reachable by Draftable. Anything on an internal network, behind a VPN, requiring a login, or returning an HTML page instead of the file itself will fail. If your documents are not publicly reachable, upload them directly instead.

​
What happens if the download fails

Draftable attempts the download up to four times. If every attempt fails, the comparison is marked as failed, and the error_message describes the download attempts. This is worth knowing when debugging: a comparison that accepted cleanly and failed later is very often a source_url that Draftable could not reach. See Handling errors and comparison failures.

​
The best of both: pre-signed storage URLs

If your documents already live in cloud storage such as Amazon S3 or Azure Blob Storage, there is a better option than either of the above. Generate a pre-signed, single-use URL and pass that as the source_url. Draftable downloads the file straight from your storage provider.
This avoids moving the data through your own servers entirely. Your application never downloads the file just to upload it again, which saves bandwidth, reduces latency, and removes your server as a bottleneck for large documents.
It also keeps your storage private. The URL grants time-limited access to one object, so the bucket itself stays closed.
Give the pre-signed URL a long enough expiry to survive the download, including retries. A URL that expires seconds after you create it can fail before Draftable has fetched the file. A window of several minutes is a reasonable starting point.

​
Which should you use?

​
Do not forget the file type

Whichever method you use, left.file_type and right.file_type are required. Draftable does not infer the type from the file name, the URL, or the content. Declaring the wrong type is a common cause of failure, and the error often surfaces only in the viewer’s JavaScript console. Accepted values are pdf, doc, docx, docm, ppt, pptx, pptm, rtf and txt.

Creating a comparison

Comparison speeds and batch processing

Handling errors and failures