Document Conversion

Uploadcare allows converting documents to the following target formats: DOC, DOCX, XLS, XLSX, ODT, ODS, RTF, TXT, PDF, JPG, PNG.

Document Conversion works via our REST API. Putting it simply, you post a conversion job and get a result once the operation is complete. If the operation is successful, you can address the outputs via respective CDN URLs, aliases in other words.

How it works

Document Conversion works via REST API, and the endpoint for the requests is:

The general Document Conversion workflow is as follows:

  1. You post a conversion job by making a REST API request; the conversion params are passed in a request together with a source file UUID. Do not forget to properly authorize your request.
  2. You wait until the conversion job status becomes finished.
  3. The converted target file can now be addressed via its UUID passed in a response; the UUID can be used for any further REST API routines. Another way to address the output is via a CDN URL alias you provided in conversion a request.

CDN URL aliases are interchangeable with respective processed file UUIDs. Check out this live example or learn more about proper URL formatting for conversion jobs.

With Document Conversion, operations are not applied on the fly. You must first post a conversion job providing a proper request parameter holding your input file identifier and a target format.

Note, Document Conversion does not alter your inputs: it creates processed outputs as separate files.

A good example of working with converted file UUIDs would be subscribing to the file.uploaded event via the webhooks REST API endpoint. This allows you to know when conversion routines are complete without checking your conversion job status. Learn more about webhooks here.

Request a conversion

POST /convert/document/

The requests you make should be in line with our general REST API workflow. The two following params should be passed in a request:

  • paths, an array of UUIDs of your source documents to convert together with the specified target format.
  • store, a flag indicating if Uploadcare should store your outputs.

When applying the same set of conversion parameters to the already converted document, a previous version of the converted file will be replaced with the new one.

When store is set to "0", your converted outputs will only be available for 24 hours. "1" indicates converted files should be made permanently available. If the parameter is omitted, we use the Auto file storing setting related to an Uploadcare project identified by the public_key provided in the auth-param.

Input file identifier formatting

Your source file identifiers should be formatted as follows:


The output format should be specified after the /-/ delimiter:


You can also provide a complete CDN URL. It can then be used as an alias to your converted file UUID:

:uuid identifies the source file you want to convert. :uuid should be followed by /document/, otherwise, your request will return an error.

/-/ is a necessary delimiter that helps our API tell file identifiers from processing operations.

The following operations are available during conversion:

  • /format/:target-format/ defines the target format you want a source file converted to. The supported values for :target-format are: pdf (default), doc, docx, xls, xlsx, odt, ods, rtf, txt, jpg, enhanced.jpg, png. In case the /format/ operation was not found, your input document will be converted to pdf.
  • /page/:number/ converts a single page of a multi-paged document to either jpg or png. The method will not work for any other target formats. :number stands for the one-based number of a page to convert.


  • Use an enhanced.jpg output format for PDF documents with inline fonts.
  • When converting multi-page documents to an image format (jpg or png), the output will be a zip archive with one image per page.

Requesting to convert a single file

Make sure to use your project keys instead of your_public_key, your_secret_key; the keys should point to an Uploadcare project with the enabled Document Conversion feature. The :uuid of the source file to convert should sit in the project specified by your_public_key. The :target-format should be set according to one of the supported formats, see this section for details.


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple your_public_key:your_secret_key" \
     -d '{"paths": [":uuid/document/-/format/:target-format/"], "store": "1"}' \


  "problems": {},
  "result": [
      "original_source": ":uuid/document/-/format/:target-format/",
      "token": 3724130,
      "uuid": ":uuid-converted"

Technically, once you convert a file you get two UUIDs: the first is included in original_source, and the second sits in uuid. That’s because of the two existing methods to address converted files.

While will work as a CDN URL alias for a converted file, the actual file identifier to use with other REST API routines would be :uuid-converted.

Conversion job output

In a response you get a JSON holding the following parameters:

  • problems, problems related to your conversion job, if any.
  • result, info related to your converted output(-s):
    • original_source, source file identifier including a target format, if present.
    • token, a conversion job token that can be used to get a job status.
    • uuid, a UUID of your converted document.

When posting a multi-file conversion job, you get separate results and status tokens for each source.

Converting multiple documents


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple your_public_key:your_secret_key" \
     -d '{"paths": [
          ":uuid"], "store": "1"}' \


  "problems": {
    ":uuid": "Bad path \":uuid\". Use :uuid/document/",
  "result": [
      "original_source": ":uuid/document/-/format/jpg/-/page/1/",
      "token": 445630631,
      "uuid": ":uuid-processed"
      "original_source": ":uuid/document/",
      "token": 445630637,
      "uuid": ":uuid-processed"

As you can see, there is a problem with one of the inputs in the above example. The problem is caused by the incorrect entry in paths: no /document/ is included in the third item.

Possible errors

Here are the errors specific to Document Conversion; you can also get errors related to our REST API.

In case you do not provide any input in the request:

[HTTP 400] \"paths\" parameter is required.
[HTTP 400] Document Conversion feature is not available for this project.

Checking conversion job status

GET /convert/document/status/:token/

Once you get a conversion job result, you can acquire a conversion job status via token. Just put it in your request URL as :token.

Get job status, example


curl -X GET \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple your_public_key:your_secret_key" \


  "status": "processing",
  "error": null,
  "result": {
    "uuid": ":uuid-processed"

Conversion job status output

A conversion job output is a JSON holding the following parameters:

  • status, conversion job status, can have one of the following values:
    • pending — a source file is being prepared for conversion.
    • processing — conversion is in progress.
    • finished — the conversion is finished.
    • failed — we failed to convert the source, see error for details.
    • canceled — the conversion was canceled.
  • error, holds a conversion error if we were unable to handle your file.
  • result, repeats the contents of your conversion output.
  • uuid, a UUID of a converted target file.

Once your conversion job is finished, you are free to add any RFC3986 compliant filenames when accessing your outputs via their CDN URL aliases, here is an example:

Possible status-check errors

In case you haven't enabled the Document Conversion feature:

[HTTP 400] Document Conversion feature is not available for this project.

In case you provided an invalid conversion job token:

[HTTP 404] Job with specified ID was not found.

In case your requests are throttled due to their high rate:

[HTTP 429] Requests rate limit hit.

The error is provided with the value for the Retry-After header and an info string like Request was throttled. Expected available in 10.0 seconds.

In case we experience an internal error with the service:

[HTTP 500] Document Conversion service error.

Document Conversion billing

The feature is avaiailable on all paid plans. We charge for document conversions separately:

  • Document Conversion is billed in units.
  • The total amount of spent conversion units can be found in your dashboard.
  • The single conversion unit costs 0.045 USD.
  • One unit accounts for 50 MB of a file subjected to conversion.
  • Conversion outputs are put to your Uploadcare project; this affects your storage limits that you can also monitor in your dashboard.
  • Each conversion operation takes one upload unit. Document conversions are applied externally, so we upload an output to your account once it is generated.
  • Your traffic limits are left intact.