ConvertApi Logo
Sign up

Asynchronous Conversions

Asynchronous file conversions are made by setting the /async path prefix. The response of the asynchronous conversion contains JobId which could be used to poll the result. The ConvertAPI supports two types of asynchronous results: - Poll and Push (WebHooks).

Poll

Asynchronous conversion request

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

It is possible to provide self generated JobId by setting query parameter JobId=rwvd6vtq58eurfwv5zw5h2ci2pgno1pn for the conversion request URL.

Response

{"JobId": "rwvd6vtq58eurfwv5zw5h2ci2pgno1pn"}

Now using JobId it is possible to retrieve the finished conversion result or get the conversion status.

Poll result request

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

Response HTTP status codes

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

Push

The ConvertAPI uses WebHooks to make result pushing. When the conversion is completed the WebHook URL is requested with the POST method and the JobId in the request body.

Asynchronous conversion request

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

Response

{"JobId": "rwvd6vtq58eurfwv5zw5h2ci2pgno1pn"}

The response includes the JobId attribute. Once the conversion is complete the WebHook URL will be called with the corresponding JobId using POST method:

POST http://www.example.com/WaitingForWebHook
...

rwvd6vtq58eurfwv5zw5h2ci2pgno1pn

The actual conversion result could be read using the received JobId.

Poll result request

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

Response HTTP status codes

  • 200 Conversion is successful. 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 two 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.