ConvertApi Logo
Sign up

Asynchronous Conversions

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 that 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.