Synchronous request

Synchronous means that when calling the API the request will wait for the pdf file to be generated before returning a response.

When to use it

Synchronous requests are useful when you want to get the results back immediately.

It is usually easier to use synchronous requests when integrating with no-code solutions such as Zapier.

If your server environment can deal with potentially having many long running connections open at the same time, then synchronous requests might be a good choice.

We recommend using Asynchronous requests for a better performance on your application.

How to use it

Send a POST request to https://api.pdforge.com/v1/pdf/sync

Body params:

Name	Type	Description
templateId (required)	string	The id of your pdf template
data (required)	object	The object containg the variables from your pdf template
convertToImage	boolean	If true, will return a .PNG file instead of a .PDF file (default: false)
metadata	object	This object containing the metadata for your PDF. See all the options here.
s3_bucket	string	The id of the active s3 connection you want to store your generated file on. (only available in the high plan)
s3_key	string	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)

The endpoint accepts only JSON data.

It's required to send the templateId parameter.

If your template has variables, it's also required to send the data object with your variables.

Request:

curl --location 'https://api.pdforge.com/v1/pdf/sync' \
--header 'Authorization: Bearer pdforge_api_123456789' \
--header 'Content-Type: application/json' \
--data '{
    "templateId": "check",
    "data":{
            "currentDDate": "01/12/2025",
            "user": {
                    "name":"John Doe",
                    "email": "[email protected]"
            },
            "details": [{"score":"100", "description":"high score"}]
    }
}
'

This endpoint responds with 200 OK once the pdf has been generated with the following body:

{
    "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
    "metadata": {
        "executionTime": "1.805 seconds",
        "fileSize": "4.066 kB"
    }
}

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 1 hour.

PDF Render Metadata

We'll also bring some additional metadata from your PDF render with every response, such as:

• executionTime - Time in seconds it took to generate your PDF

• fileSize - PDF size in kiloBytes

Request timeout (>30 seconds to render)

Sometimes, your PDF might take more than 30 seconds to render, if it has a lot of heavy images/charts and a lot of pages being generated.

If that's the case and your PDF takes more than 30 seconds to render synchronously, we'll automatically add it to an asynchronous queue to render it.

You'll receive a response with status 202 and a body like this:

{
    "requestId": "pdforge_request_123456789",
    "statusUrl": "https://api.pdforge.com/v1/pdf/status/pdforge_request_123456789",
    "message": "Couldn't generate PDF within 30 seconds, a queue was added to generate it asynchronously. Check the queue status on this URL."
}

You'll be able to check if the PDF is completed using our endpoint v1/pdf/status/:requestId, with the requestId you just received (or just by making a GET request on the statusUrl).

If the PDF is still rendering, you'll get a response like this:

{
    "requestId": "pdforge_request_123456789",
    "renderStatus": "ONGOING",
    "signedUrl": "",
    "metadata": {}
}

And once the PDF is ready, you'll receive a response like this:

{
    "requestId": "pdforge_request_123456789",
    "renderStatus": "SUCCESS",
    "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
    "metadata": {
        "executionTime": "1.805 seconds",
        "fileSize": "4.066 kB"
    }
}