---
title: "Render PDF"
method: POST
path: "/v2/organizations/{organizationId}/templates/{externalId}/render"
tags: ["Rendering"]
---

# Render PDF

`POST /v2/organizations/{organizationId}/templates/{externalId}/render`

## Request

- Base URL: `https://api.pdfs.build`
- URL: `https://api.pdfs.build/v2/organizations/{organizationId}/templates/{externalId}/render`
- Auth: HTTP bearer

Validates `data` against the template's schema, compiles the template, and returns the PDF. Requires a published template and a plan with REST API access (Starter and higher).

Send `"async": true` to render in the background instead: the response is `202` with a job handle; poll the job or wait for the `render.completed` / `render.failed` webhook. Async renders count toward the same monthly quota as synchronous ones.

Webhook events for this render go to every enabled endpoint of the organization, or only to the endpoints in `webhookIds` when provided (an empty list sends nowhere).

## Request body

- RenderRequest
  - `data` object: Key-value pairs matching the template's schema. Defaults to `{}`.
  - `async` boolean: Render in the background and return `202` with a job handle. `version` is resolved when the job is queued, as for a batch: one that does not exist is a `400`, and a channel is held to the version it named then.
  - `webhookIds` string[]: Restrict this render's webhook events to these endpoint ids (`whe_...`). Unknown ids fail with `422 unknown_webhook_ids`. Omitted: all enabled endpoints. `[]`: none.
  - `version` union: Which content to render. Omitted or `null` resolves through the `latest` channel, which follows promotions rather than in-progress edits. A positive integer pins a version number, `"draft"` renders the mutable working copy, and any other string names a channel.
    - integer
    - string

## Response `200`

The rendered PDF.

## Other responses

- `202`: Async render accepted and queued.
- `400`: `data` does not match the template schema (`Validation failed` with `details`), an invalid `version` selector, or `invalid_external_id`.
- `401`: Missing, invalid or expired API key.
- `402`: `api_renders_not_allowed_on_free` — REST renders need Starter or higher.
- `403`: `draft_not_renderable` (publish first) or `organization_scope_mismatch`.
- `404`: No template with that id is accessible to this key. Another user's draft is indistinguishable from a missing template.
- `422`: The template failed to compile with this data (`Compilation failed` with `diagnostics`), or `unknown_webhook_ids`.
- `429`: `render_quota_exceeded` — this billing period's render quota is used up. Upgrade or buy a top-up pack.
- `500`: Rendering failed for a reason that is not the template or the data. Safe to retry.

---

[API](https://skmtc.dev/pdfs/apis/pdfs-build-api.md) · [All operations](https://skmtc.dev/pdfs/apis/pdfs-build-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pdfs/apis/pdfs-build-api/revisions/1c7340b9521d?raw)