PDFs

Besides images, Stencil supports generating PDFs from the same template.

Create a PDF asynchronously

POST 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*	string	The ID of the template

202: Accepted PDF is accepted for processing

{
  "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.

PDF generation uses 2 credits instead of 1.

Get the PDF

GET https://api.usestencil.com/v1/pdfs/:pdf_id

Path Parameters

Name	Type	Description
pdf_id*	string	The PDF id. You can get the PDF id from the response of creating a PDF

200: OK

{
  "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
}
       

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

Search generated PDFs

POST /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

200

{
  "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"
    }
  ]
}