# PDFs

## Create a PDF asynchronously

<mark style="color:green;">`POST`</mark> `https://api.usestencil.com/v1/pdfs`

#### Request Body

| Name                                       | Type   | Description                                               |
| ------------------------------------------ | ------ | --------------------------------------------------------- |
| modfications                               | array  | Array of modification objects                             |
| metadata                                   | object | Extra metadata to be included together with the webhook   |
| webhook\_url                               | string | URL of the webhook to be called when the pdf is generated |
| template<mark style="color:red;">\*</mark> | string | The ID of the template                                    |

{% tabs %}
{% tab title="202: Accepted PDF is accepted for processing" %}

```json
{
  "created_at": "2023-04-06T12:04:58.877Z",
  "id": "e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "log": null,
  "metadata": {},
  "modifications": [
    {
      "name": "image_2",
      "src": "https://usestencil.s3.amazonaws.com/dev/uploads/814bb298-a5c9-4df8-b367-cb81be9e8839/efaa4261-94d7-4ceb-b2ec-cf60990afb07/photo-1613569973485-c6ecb241be47-311746964.png"
    },
    {
      "name": "text_3",
      "text": "YELLOW WOOL HOODIEZZ"
    },
    {
      "name": "text_5",
      "text": "USD 49.99"
    }
  ],
  "pdf_url": null,
  "self": "http://api.usestencil.test:4000/v1/pdfs/e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "status": "pending",
  "template_id": "6132c433-aa49-4774-8eed-c402898f1437",
  "webhook_response_body": null,
  "webhook_response_code": null,
  "webhook_url": null
}
```

You can send a `GET` request to `self` to check the status of PDF generation. See the next API for details.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
PDF generation uses 2 credits instead of 1.
{% endhint %}

## Get the PDF

<mark style="color:blue;">`GET`</mark> `https://api.usestencil.com/v1/pdfs/:pdf_id`

#### Path Parameters

| Name                                      | Type   | Description                                                                                 |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------- |
| pdf\_id<mark style="color:red;">\*</mark> | string | <p>The PDF id. </p><p></p><p>You can get the PDF id from the response of creating a PDF</p> |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "created_at": "2023-04-06T12:04:58.877Z",
  "id": "e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "log": null,
  "metadata": {},
  "modifications": [
    {
      "name": "image_2",
      "src": "https://usestencil.s3.amazonaws.com/dev/uploads/814bb298-a5c9-4df8-b367-cb81be9e8839/efaa4261-94d7-4ceb-b2ec-cf60990afb07/photo-1613569973485-c6ecb241be47-311746964.png"
    },
    {
      "name": "text_3",
      "text": "YELLOW WOOL HOODIEZZ"
    },
    {
      "name": "text_5",
      "text": "USD 49.99"
    }
  ],
  "pdf_url": "https://usestencil.s3.amazonaws.com/dev/pdfs/6132c433-aa49-4774-8eed-c402898f1437/e45e9dc7-8eee-476c-9031-0d1040881d1a.pdf",
  "self": "http://api.usestencil.test:4000/v1/pdfs/e45e9dc7-8eee-476c-9031-0d1040881d1a",
  "status": "completed",
  "template_id": "6132c433-aa49-4774-8eed-c402898f1437",
  "webhook_response_body": null,
  "webhook_response_code": null,
  "webhook_url": null
}
       
```

{% endtab %}
{% endtabs %}

For PDF generation, we only support asynchronous request, as PDF generation usually takes a slightly longer time than image generation.

## Search generated PDFs

<mark style="color:green;">`POST`</mark> `/v1/pdfs/search?q=<query>`

Search for generated PDFs based on your modification inputs. It searches for given query in your modification inputs.  Query is case insensitive.

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "meta": {
    "next": null,
    "total_count": 1,
    "previous": null
  },
  "results": [
    {
      "id": "fa032cc8-fa07-4221-8411-4279b46683d5",
      "status": "completed",
      "self": "http://api.usestencil.com/v1/pdfs/fa032cc8-fa07-4221-8411-4279b46683d5",
      "log": "{}",
      "metadata": {},
      "created_at": "2025-09-23T11:56:21.562Z",
      "template_id": "8be62eca-72de-4f81-9edc-a4dbeee6986f",
      "webhook_url": null,
      "modifications": [
        {
          "name": "rect_4"
        },
        {
          "name": "image",
          "src": "https://images.unsplash.com/photo-1503327431567-3ab5e6e79140?q=80&w=3328&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
        },
        {
          "name": "product",
          "text": "JEANS"
        },
        {
          "name": "price",
          "text": "$49.99"
        },
        {
          "name": "qrcode_5",
          "value": "https://usestencil.com"
        }
      ],
      "webhook_response_code": null,
      "webhook_response_body": null,
      "pdf_url": "https://usestencil.s3.amazonaws.com/dev/pdfs/8be62eca-72de-4f81-9edc-a4dbeee6986f/fa032cc8-fa07-4221-8411-4279b46683d5.pdf"
    }
  ]
}

```

{% endtab %}
{% endtabs %}