Document conversion

Conversion formats info

You can determine the file format and possible conversion formats using a request:

https://api.uploadcare.com/convert/document/:UUID/

curl -X GET \
    -H "Content-Type: application/json" \
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
    "https://api.uploadcare.com/convert/document/:UUID/"bash

Get $YOUR_PUBLIC_KEY and $YOUR_SECRET_KEY from API keys.

File info in response:

{
    "format": {
        "name": "jpg",
        "conversion_formats": [{
            "name": "avif"
        }, {
            "name": "bmp"
        }, {
            "name": "gif"
        }, {
            "name": "ico"
        }, {
            "name": "pcx"
        }, {
            "name": "pdf"
        }, {
            "name": "png"
        }, {
            "name": "ps"
        }, {
            "name": "svg"
        }, {
            "name": "tga"
        }, {
            "name": "thumbnail"
        }, {
            "name": "tiff"
        }, {
            "name": "wbmp"
        }, {
            "name": "webp"
        }]
    }
} json

Check out API reference for GET /convert/document/:UUID/.

Processing job

The endpoint for document conversion request is:

https://api.uploadcare.com/convert/document/

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
    -d '{"paths": [":UUID/document/-/format/:target_format/"], "store": "1"}' \
    "https://api.uploadcare.com/convert/document/"bash

Project pointed with $YOUR_PUBLIC_KEY and $YOUR_SECRET_KEY should have enabled Document conversion feature. The :UUID of the source file to convert should belong to the project.

Input file identifiers should be formatted with UUID followed by /document/ (please note, this is not operation, so there shouldn't be /-/ between them) and ended by operations separated by /-/:

https://ucarecdn.com/:uuid/document/-/format/:target_format/

The following operations are available for the conversion job:

• /format/:target_format/ — defines the target conversion format.
• /page/:number/ — converts a single page of a multi-page document to either jpg or png. This method won't work for other target formats. :number — is a one-based number for a page to convert.

Operations can be omitted; the document will then be delivered as a PDF.

Check out detailed API reference for POST /convert/document/.

Webhook event

To get the job result, you need to enable file.uploaded in the Webhook section of the dashboard.

After completing the processing job, the webhook will be sent to the endpoint you specified in the webhook settings.

File information in response:

"initiator": {
      "type": "addon",
      "detail": {
          "addon_name": "zamzar_convert_document",
          "request_id": "80c78d01-f8b6-432a-bb1f-b707f86e0106",
          "source_file_uuid": ":UUID"
      }
   }
  "hook": {
    ...
    "event": "file.uploaded",
    "is_active": true,
    "version": "0.7",
    "created_at": "2023-10-26T09:32:40.114516Z",
    "updated_at": "2023-10-26T09:32:40.114516Z"
  },
  "data": {
    "content_info": {
      "mime": {
        "mime": "text/plain",
        "type": "text",
        "subtype": "plain"
      }
    },
    "uuid": ":new_UUID",
    "is_image": false,
    "is_ready": true,
    "metadata": {},
    "appdata": {
      "uc_clamav_virus_scan": {
        "data": {
          "infected": false
        },
        "version": "1.0.1",
        "datetime_created": "2023-10-26T17:29:30.331Z",
        "datetime_updated": "2023-10-26T17:29:30.331Z"
       }
     }
  }  json

After receiving source_file_uuid, you can make a GET request for the original file and get all the variations from there:

"uuid": ":UUID", "variations": {
    "document/-/format/txt/": ":new_UUID"
}json

Job status

If your application does not have a backend or uses a mobile version, you can submit the request yourself.

As a request result, you immediately receive an UUID of the new file. But it cannot be accessible due to that conversion takes time. Once you get a processing job result, you can get a processing job status using :token.

curl -X GET \
    -H "Content-Type: application/json" \
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
    "https://api.uploadcare.com/convert/document/status/:token/"bash

Check out detailed API reference for GET /convert/document/status/:token/.

Job result

The processed document becomes addressable via both a new UUID and a CDN URL you provided in the request:

https://ucarecdn.com/:new_uuid/
https://ucarecdn.com/:original_uuid/document/-/:operation/:parameters/

Applying the same set of conversion operations to the original document will create a new file with a different :new_UUID, the conversion result will be the same.

An archive

To save converted pages of a multi-page document as an archive, you must pass the save_in_group=0 parameter in the request to set up the conversion task:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
    -d '{"paths": [":UUID/document/-/format/:target-format/"], "store": "1", "save_in_group":"0"}' \
    "https://api.uploadcare.com/convert/document/"bash

You can define possible :target-format for original file.

Note: When converting multi-page documents into image format (:target-format=jpg or :target-format=png), the output will be a zip archive with files, where each document page will be a separate image.

The response will contain the UUID of zip archive:

{
    "result": [{
        "original_source": ":UUID/document/-/format/:target_format/",
        "token": ":token",
        "uuid": ":zip_UUID"
    }],
    "problems": {}
}json

A zip archive with all converted pages can be downloaded via URL with the :zip_UUID:

https://ucarecdn.com/:zip_UUID/

Separate files

To form a group of files from converted pages of a multi-page document, you must pass the save_in_group=1 parameter and choose :target-format as image format (jpg or png) in the request to set up the conversion task:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
    -d '{"paths": [":UUID/document/-/format/:target-format/"], "store": "1", "save_in_group":"1"}' \
    "https://api.uploadcare.com/convert/document/"bash

Note: The API response to the conversion request doesn't indicate the group UUID since the group identifier includes the number of files in the group, which is determined later.

To get the group UUID of the converted files group:

curl -X GET \
    -H "Content-Type: application/json" \
    -H "Accept: application/vnd.uploadcare-v0.7+json" \
    -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
    "https://api.uploadcare.com/convert/document/:UUID/"bash

The response will contain the group UUID:

{
    "error": null,
    "format": {
        "name": "pdf",
        ...
    },
    "converted_groups": {
        ":target_format": ":group_UUID"
    }
}json

You can view all files in a group by URL:

https://ucarecdn.com/:group_UUID/

To further work with group files, use the group REST API.

More about multi-page conversion

If the source document is not multi-page or the conversion of a specific page is requested, for example, :UUID/document/-/format/jpg/-/page/1/, then creating a group is impossible.

All files of converted pages of one multipage document will be added to variations in the same way as if the conversion of each page was requested separately: {"document/-/format/:target_format/-/page/:page_number/": "file_uuid", ...}

Information about the groups formed based on the conversion results to different formats can be obtained from the /convert/document/:UUID/ endpoint. In response to a request to the endpoint, the identifiers of the formed groups will be available along the path .format.converted_groups in the form of a dictionary: {":target_format": ":group_UUID", ...}

If the same file is converted again to the same format, the group ID in the response will be updated, but the previous group and its files will not be deleted.