> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pdfnoodle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Asynchronous Request
> Asynchronous means that the request will return immediately with a requestId (if the request passes validation), but the pdf file will be sent after a few seconds to your custom webhook.
We recommend using asynchronous requests for better performance on your
application.
POST [https://api.pdfnoodle.com/v1/html-to-pdf/async](https://api.pdfnoodle.com/v1/html-to-pdf/async)
## Request
```bash cURL theme={null}
curl --location 'https://api.pdfnoodle.com/v1/html-to-pdf/async' \
--header 'Authorization: Bearer pdfnoodle_api_123456789' \
--header 'Content-Type: application/json' \
--data '{
"html": "Your HTML here!
",
"webhook": "https://webhook.url"
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.pdfnoodle.com/v1/html-to-pdf/async", {
method: "POST",
headers: {
Authorization: "Bearer pdfnoodle_api_123456789",
"Content-Type": "application/json",
},
body: JSON.stringify({
html: "Your HTML here!
",
webhook: "https://webhook.url",
}),
});
const result = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.pdfnoodle.com/v1/html-to-pdf/async',
headers={
'Authorization': 'Bearer pdfnoodle_api_123456789',
'Content-Type': 'application/json'
},
json={
'html': 'Your HTML here!
',
'webhook': 'https://webhook.url'
}
)
result = response.json()
```
## Response
```json Immediate Response (200 OK) theme={null}
{
"requestId": "pdfnoodle_request_123456789"
}
```
```json Webhook Response (SUCCESS) theme={null}
{
"requestId": "pdfnoodle_request_123456789",
"renderStatus": "SUCCESS",
"signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
"metadata": {
"executionTime": "1.805 seconds",
"fileSize": "4.066 kB"
}
}
```
```json Webhook Response (FAILED) theme={null}
{
"requestId": "pdfnoodle_request_123456789",
"renderStatus": "FAILED",
"signedUrl": "",
"metadata": {}
}
```
This endpoint responds with `200 OK` immediately with a `requestId`. After a few seconds, the PDF file will be generated and we will send a POST to your webhook with the response body shown above.
The `renderStatus` could be either `SUCCESS` or `FAILED`.
If the request `FAILED`, you should contact support to figure out why your PDF
generation failed.
The response body will contain a `signedUrl` key which is a temporary URL pointing to the generated PDF file on our S3 bucket. If you passed a custom `s3_bucket`, it'll be stored there instead. This URL will expire after the time specified in `signedUrlExpiresIn` (default: 1 hour).
### PDF Render Metadata
We'll also bring some additional metadata from your PDF render with every response:
* **executionTime** - Time in seconds it took to generate your PDF
* **fileSize** - PDF size in kiloBytes
## Parameters
The HTML content you want to render
The url of your webhook
The object containing the parameters for your PDF. [See all the options
here](/api-reference/options/pdf-params).
If true, will return a .PNG file instead of a .PDF file
This object containing the metadata for your PDF. [See all the options
here](/api-reference/options/pdf-metadata).
The id of the active s3 connection you want to store your generated file on.
(only available in the high plan)
The path, including subdirectories and the filename without extension, to use
when saving the render in your S3 bucket. (only available if being stored in
custom s3\_bucket)
Number of seconds that the generated signed URL will take to expire (default:
1 hour)
If true, will hide the footer and the header elements on the first page of the
generated PDF
## Checking PDF Status
Instead of waiting for the webhook, you can also check the status of your PDF generation by polling the [Get PDF Status](/api-reference/pdf-status/get) endpoint using the `requestId` returned from this request.