Asynchronous File Conversions

Asynchronous file conversions are made by setting parameter Async to True. The Response of the asynchronous conversion contains JobId which could be used to poll the result. The ConvertAPI support two types of asynchronous result - polling and WebHooks.

Result polling

Asynchronous conversion example
Request:
POST https://v2.convertapi.com/convert/docx/to/pdf?Secret=XXX&Async=true&File=http://example.com/myfile.docx
Response:
{
    "JobId": "d3bd2056-4330-4cf3-9b18-483a2412dd6b"
}

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

Poll result
Request:
GET https://v2.convertapi.com/job/d3bd2056-4330-4cf3-9b18-483a2412dd6b

WebHooks

The ConvertAPI support WebHooks, when conversion is done the WebHook URL is called with JobId. The conversion request should include WebHook parameter with URL which should be called.

Asynchronous conversion example
Request:
POST https://v2.convertapi.com/convert/docx/to/pdf?Secret=XXX&Async=true&WebHook=http://www.example.com/WaitingForWebHook&File=http://example.com/myfile.docx
Response:
{
    "JobId": "d3bd2056-4330-4cf3-9b18-483a2412dd6b"
}
The response will include JobId and when conversion is finished the WebHook URL will be called with the same JobId using GET method.
WebHook GET call
    http://www.example.com/WaitingForWebHook?JobId=d3bd2056-4330-4cf3-9b18-483a2412dd6b
After JobId is received we can poll conversion result.
Poll result
Request:
GET https://v2.convertapi.com/job/d3bd2056-4330-4cf3-9b18-483a2412dd6b

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.

Semi-Asynchronous file conversions

Semi-Asynchronous file conversions are useful when connection to ConvertAPI is lost during large file conversion. To avoid repetitive conversion, provide JobId parameter with self generated UUID (RFC 4122).

Semi-Asynchronous conversion example
Request:
POST https://v2.convertapi.com/convert/docx/to/pdf?Secret=XXX&JobId=d3bd2056-4330-4cf3-9b18-483a2412dd6b&File=http://example.com/myfile.docx

In case of disrupted connection treat this conversion as if it was asynchronous conversion. Retrieve conversion result like described in asynchronous conversion section.

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 job is no longer required it can be deleted.

Deleting d3bd2056-4330-4cf3-9b18-483a2412dd6b job
Request:
DELETE https://v2.convertapi.com/job/d3bd2056-4330-4cf3-9b18-483a2412dd6b

Response HTTP status codes

  • 200 - deleted successful.
  • 404 - JobId is invalid or already deleted.
  • 5XX - delete error. Response is an error message.