Async Conversions

🚧

Use it only when necessary!

Modern HTTP clients are equipped to handle long-running requests without the need for asynchronous callbacks. It can maintain a connection and wait for extended periods without timing out, making it unnecessary to rely on the older asynchronous conversion method, which creates a job and triggers a callback when the conversion is complete. Unless you're facing specific constraints, such as strict timeout limits or dealing with legacy systems, we recommend using your HTTP client to handle the full conversion request.

Asynchronous conversions can be particularly useful in situations where you are dealing with large files or complex conversion processes that take a significant amount of time to complete. Instead of keeping the client waiting and risking timeouts, the asynchronous method allows you to offload the conversion task to a separate job. This method creates a job in the background and notifies your system via a callback once the process is complete (or you can poll to get the conversion result).

Asynchronous file conversions are made by setting the /async path prefix. The response of the asynchronous conversion contains the JobId parameter, which can be used to get the conversion result. Optionally, you can subscribe to a WebHook with your specified URL, which will be called after the successful conversion.

Asynchronous conversion request

[POST]
https://v2.convertapi.com/async/convert/docx/to/pdf?Secret=your-api-secret&File=http://example.com/myfile.docx

Optionally, it is possible to provide a self-generated JobId by setting the query parameter JobId=rwvd6vtq58eurfwv5zw5h2ci2pgno1pn for the conversion request URL. The JobId must be 32 characters long, only lowercase letters and numbers.

Response

{"JobId": "rwvd6vtq58eurfwv5zw5h2ci2pgno1pn"}

Poll result request

Now using the JobId, you can retrieve the finished conversion result or get the conversion status (see HTTP status codes below).

[GET]
https://v2.convertapi.com/async/job/rwvd6vtq58eurfwv5zw5h2ci2pgno1pn

Webhook (PUSH notification)

The ConvertAPI uses WebHooks to push the notification about the conversion completion. When the conversion is completed, the WebHook URL is requested using the POST method with the JobId in the request body.

To receive a push notification to your preferred URL, please provide the WebHook query parameter when making an async request:

[POST]
https://v2.convertapi.com/async/convert/docx/to/pdf?Secret=your-api-secret&WebHook=http://www.example.com/WaitingForWebHook&File=http://example.com/myfile.docx

Once the conversion is complete, the WebHook URL will be called with the corresponding JobId using the POST method:

POST http://www.example.com/WaitingForWebHook
Content-Type: "application/json"
...

{"JobId": "rwvd6vtq58eurfwv5zw5h2ci2pgno1pn"}

The actual conversion result can be retrieved using the received JobId.

Get the conversion result

To receive the converted file result, please make a GET request to the https://v2.convertapi.com/async/job/<your-job-id> endpoint. This endpoint will be available for three hours after the conversion or until you delete the job manually.

[GET]
https://v2.convertapi.com/async/job/rwvd6vtq58eurfwv5zw5h2ci2pgno1pn

Response HTTP status codes

• 200 Conversion is successful. The response is a conversion result.
• 202 Conversion in progress.
• 404 JobId is invalid or response is expired.
• 5XX Conversion error. Response is an error message.

Delete job

If the job is no longer required, it can be deleted using the DELETE request, or it would be automatically deleted after a maximum of three hours.

Delete job request

[DELETE]
https://v2.convertapi.com/async/job/rwvd6vtq58eurfwv5zw5h2ci2pgno1pn

Response HTTP status codes

• 200 Deleted successfuly.
• 404 JobId is invalid or job is already deleted.
• 5XX Delete error. Response is an error message.