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.
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
Poll result request
Now using the JobId, you can retrieve the finished conversion result or get the conversion status (see HTTP status codes below).
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:
Once the conversion is complete, the WebHook URL will be called with the corresponding JobId using the POST method:
The actual conversion result can be retrieved using the received JobId.
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.
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.
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
200 Deleted successfuly.
404 `JobId` is invalid or job is already deleted.
5XX Delete error. Response is an error message.
Asynchronous conversion request
[POST]
https://v2.convertapi.com/async/convert/docx/to/pdf?Secret=your-api-secret&File=http://example.com/myfile.docxOptionally, 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/rwvd6vtq58eurfwv5zw5h2ci2pgno1pnWebhook (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.docxOnce 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/rwvd6vtq58eurfwv5zw5h2ci2pgno1pnResponse 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/rwvd6vtq58eurfwv5zw5h2ci2pgno1pnResponse HTTP status codes
200 Deleted successfuly.
404 `JobId` is invalid or job is already deleted.
5XX Delete error. Response is an error message.
Updated on: 22/02/2024
Thank you!