Async Conversion

The async conversion endpoint processes your request and immediately acknowledges receipt, promising to send a callback to your specified webhook once rendering is complete. This method is ideal for workflows where immediate results aren't required, but you need to be notified upon completion. It is particularly useful when you have a large number of documents to generate, especially when combined with uploading to your S3 storage. An additional webhook parameter is required in the request body.

Endpoint Details

Method: POST

https://api.pdfbolt.com/v1/async

Success Example

Request

{
  "url": "https://example.com",
  "webhook": "https://your-example-webhook.com"
}

Response

{
  "requestId": "b32bb5ce-483a-44ab-9239-52c0e3b0ff6c"
}

Webhook Request

{
  "requestId": "b32bb5ce-483a-44ab-9239-52c0e3b0ff6c",
  "status": "SUCCESS",
  "errorCode": null,
  "errorMessage": null,
  "documentUrl": "https://s3-your-custom-bucket.com/document.pdf",
  "expiresAt": "2024-11-19T23:59:59Z",
  "isAsync": true,
  "duration": 1000,
  "documentSizeMb": 0.36
}

Failure Example

Request

{
  "url": "https://example.com",
  "webhook": "https://your-example-webhook.com",
  "waitForFunction": "() => window.innerWidth < 100"
}

Response

{
  "requestId": "7e075770-9c50-4018-a877-fc45c45b7850"
}

Webhook Request

{
  "requestId": "7e075770-9c50-4018-a877-fc45c45b7850",
  "status": "FAILURE",
  "errorCode": "GATEWAY_TIMEOUT",
  "errorMessage": "Timeout exceeded. Check parameters such as waitForFunction, waitForSelector, and timeout in your request.",
  "documentUrl": null,
  "expiresAt": null,
  "isAsync": true,
  "duration": null,
  "documentSizeMb": null
}

Body Parameters

info

In this section, you will find only the parameters specific to the /async endpoint. To view the list of common parameters shared across all endpoints, please refer to the Conversion Parameters section.

customS3PresignedUrl

Type: string (URL)

Required: No

Details: The customS3PresignedUrl property allows you to specify a URL for uploading your document directly to your S3 bucket. For more information on setting this up, please refer to Uploading to Your S3 Bucket section. If you don't provide this URL, your document will be temporarily stored in our S3 bucket for 1 hour.

Usage:

{
  "url": "https://example.com",
  "customS3PresignedUrl": "https://s3-your-custom-bucket.com?token=abcdef"
}

contentDisposition

Type: string

Required: No

Default Value: inline

Details: This parameter specifies how the content should be presented when downloaded from the S3 bucket. It determines whether the file will be displayed inline in the browser or downloaded as an attachment.

• inline - the PDF will be displayed directly in the browser.
• attachment - the PDF will be downloaded as a file, prompting the user with a "Save As" dialog.

Usage:

{
  "url": "https://example.com",
  "contentDisposition": "attachment"
}

additionalData

Type: object

Required: No

Details: This parameter is an object containing up to 10 key-value pairs, which will be sent as headers in the callback request to your webhook. This allows you to provide context, personalize responses, or assist in debugging and tracking.

Usage:

{
  "url": "https://example.com",
  "additionalData": {
    "transactionId": "10589654"
  }
}

tip

The additionalData parameter helps provide context, personalize responses, or assist in debugging and tracking.

additionalWebhookHeaders

Type: object Required: No

Details: The additionalWebhookHeaders parameter is used to send extra information as headers in asynchronous processing webhook requests. You can include a maximum of 10 headers.

Usage Example:

{
  "url": "https://example.com",
  "additionalWebhookHeaders": {
    "X-Custom-Header-1": "Value1",
    "X-Custom-Header-2": "Value2"
    // up to 10 headers
  }
}

tip

Use the additionalWebhookHeaders parameter to add context, customize responses, or facilitate debugging and tracking in your webhook workflows.

Response Parameters

Parameter	Type	Description	Possible Values	Example Value
requestId	string (UUID)	Unique identifier for the request.	Any valid UUID	ee57bcb5-b02b-4ae7-af37-6e91549f647d

Webhook Request Parameters

Parameter	Type	Description	Possible Values	Example Value
requestId	string (UUID)	Unique identifier for the request.	Any valid UUID	ee57bcb5-b02b-4ae7-af37-6e91549f647d
status	string (Enum)	Status of the request.	SUCCESS FAILURE	SUCCESS
errorCode	string	Error code. Will be null if status is SUCCESS.	Refer to errorCode values in the HTTP Status Codes table for all possible values	GATEWAY_TIMEOUT
errorMessage	string	Error message. Will be null if status is SUCCESS.	Any string or null	Timeout exceeded. Check parameters such as waitForFunction, waitForSelector, and timeout in your request.
documentUrl	string (URL)	URL to the generated document.	Any valid URL	https://s3-your-custom-bucket.com/document.pdf
expiresAt	string (ISO 8601)	Expiration date and time of the document. Will be null if customS3PresignedUrl is provided.	ISO 8601 datetime string in UTC or null	2024-11-19T23:59:59Z or null
isAsync	boolean	Indicates if the operation is asynchronous. Will always be true for the /async endpoint.	true false	true
duration	number	Duration of the request in milliseconds. Will be null if status is FAILURE.	Any positive number or null	1000 or null
documentSizeMb	number	Size of the document in megabytes. Will be null if status is FAILURE.	Any positive number or null	0.36 or null