> ## 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.

# Synchronous request

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

<Note>
  We recommend using asynchronous requests for better performance on your
  application.
</Note>

POST [https://api.pdfnoodle.com/v1/pdf/sync](https://api.pdfnoodle.com/v1/pdf/sync)

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api.pdfnoodle.com/v1/pdf/sync' \
  --header 'Authorization: Bearer pdfnoodle_api_123456789' \
  --header 'Content-Type: application/json' \
  --data '{
      "templateId": "check",
      "data": {
          "currentDDate": "01/12/2025",
          "user": {
              "name": "John Doe",
              "email": "john.doe@email.com"
          },
          "details": [{"score": "100", "description": "high score"}]
      }
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.pdfnoodle.com/v1/pdf/sync", {
    method: "POST",
    headers: {
      Authorization: "Bearer pdfnoodle_api_123456789",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      templateId: "check",
      data: {
        currentDDate: "01/12/2025",
        user: {
          name: "John Doe",
          email: "john.doe@email.com",
        },
        details: [{ score: "100", description: "high score" }],
      },
    }),
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.pdfnoodle.com/v1/pdf/sync',
      headers={
          'Authorization': 'Bearer pdfnoodle_api_123456789',
          'Content-Type': 'application/json'
      },
      json={
          'templateId': 'check',
          'data': {
              'currentDDate': '01/12/2025',
              'user': {
                  'name': 'John Doe',
                  'email': 'john.doe@email.com'
              },
              'details': [{'score': '100', 'description': 'high score'}]
          }
      }
  )

  result = response.json()
  ```
</CodeGroup>

## Response

<CodeGroup>
  ```json Success (200 OK) theme={null}
  {
    "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
    "metadata": {
      "executionTime": "1.805 seconds",
      "fileSize": "4.066 kB"
    }
  }
  ```

  ```json Timeout (202 Accepted) theme={null}
  {
    "requestId": "pdfnoodle_request_123456789",
    "statusUrl": "https://api.pdfnoodle.com/v1/pdf/status/pdfnoodle_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."
  }
  ```
</CodeGroup>

This endpoint responds with `200 OK` once the PDF has been generated. 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).

If your PDF takes more than 30 seconds to render, it will automatically be added to an asynchronous queue and you'll receive a `202 Accepted` response with a `requestId`. You can check the status using the [Get PDF Status](/api-reference/pdf-status/get) endpoint.

### 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

<ParamField body="templateId" type="string" required>
  The id of your PDF template
</ParamField>

<ParamField body="data" type="object" required>
  The object containing the variables from your PDF template
</ParamField>

<ParamField body="convertToImage" type="boolean" default="false">
  If true, will return a .PNG file instead of a .PDF file
</ParamField>

<ParamField body="metadata" type="object">
  This object containing the metadata for your PDF. [See all the options
  here](/api-reference/options/pdf-metadata).
</ParamField>

<ParamField body="s3_bucket" type="string">
  The id of the active s3 connection you want to store your generated file on.
  (only available in the high plan)
</ParamField>

<ParamField body="s3_key" type="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)
</ParamField>

<ParamField body="signedUrlExpiresIn" type="number" default="3600">
  Number of seconds that the generated signed URL will take to expire (default:
  1 hour)
</ParamField>

<ParamField body="externalId" type="string">
  If you're using our embedded white-label solution, you can pass the UUID of
  your customer to generate the PDF of the customized template
</ParamField>

<ParamField body="hasCover" type="boolean" default="false">
  If true, will hide the footer and the header elements on the first page of the
  generated PDF
</ParamField>

<ParamField body="debug" type="boolean" default="false">
  If true, will enter Debug Mode and show additional properties on the response
  to help you figure out your variables and html rendered content. [Here's
  everything you need to know about Debug
  Mode](/api-reference/options/debug-mode)
</ParamField>

## Request Timeout (>30 seconds)

<Warning>
  Synchronous requests are useful when you want to get the results back
  immediately. However, if your PDF takes more than 30 seconds to render, it
  will automatically be added to an asynchronous queue.
</Warning>

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 be able to check if the PDF is completed using the [Get PDF Status](/api-reference/pdf-status/get) endpoint 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:

```json theme={null}
{
  "requestId": "pdfnoodle_request_123456789",
  "renderStatus": "ONGOING",
  "signedUrl": "",
  "metadata": {}
}
```

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

```json 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"
  }
}
```