PDFs API

The PDFs API, also called the Document Generation API, creates court-ready PDF documents over HTTPS. It is a standalone eCourtDate product with its own base URL, its own documentation site, and its own API keys.

This page is a high-level orientation. The full endpoint documentation, request and response schemas, and interactive console live at docs.pdfs.ecourtdate.com.

What you can build with it

Reusable templates with merge tags: define a layout once, publish it as an immutable version, then generate documents by posting only the data.
One-off documents: generate a document from a blank page or from HTML and CSS, without creating a template first.
Rich field types: text (plain or Markdown), form fields, checkboxes, symbols, AcroForm fill, images, barcodes (QR and Code 128), tables, and HTML.
Image assets: upload and reuse logos, seals, and signatures across documents.
Batch generation: submit up to 200 documents in a single job and poll for the result.
Audit trail: a per-account record of what was generated and when, including the person each action was carried out on behalf of.

Common uses include hearing notices, summonses, citations, receipts, compliance letters, and any other document a court or agency needs to produce in volume and keep a record of.

Base URL

https://api.pdfs.ecourtdate.com/v1

The service is HTTPS only. There is no separate staging environment for the PDFs API. Coordinates in document layouts are expressed in PDF points with a top-left origin.

Authentication

The PDFs API uses a scoped API key sent in the x-api-key header on every request. This is different from the eCourtDate platform API, which issues a client_id and client_secret that you exchange for a Bearer token.

Create a key in the eCourtDate Console under APIs at console.ecourtdate.com/apis, selecting the PDFs API when you create the client. See eCourtDate APIs for the shared credential process across all eCourtDate APIs.

API selection

The step that lets you choose which API a client belongs to is rolling out alongside the standalone API products. If you do not see it yet, open a support ticket in the Console using the Help button in the bottom-right corner and ask for a PDFs API key.

Scopes

Grant each key the narrowest set of scopes that lets it do its job.

Scope	Grants
`templates:read`	Browse templates and previews
`templates:write`	Create and publish templates
`generate`	Create documents and access the generated outputs
`audit:read`	Read the audit trail

Attributing writes

Write requests, such as creating a template or publishing a version, also require an X-On-Behalf-Of header naming the person the request is being made for. The audit trail records that value as the acting person, so an API key shared by a backend service still produces a per-person record. The documented examples use an email address:

X-On-Behalf-Of: clerk@example.gov

Handling keys

Store keys in a secrets manager. Never commit them to source control and never expose them in client-side code. To rotate a key, create the replacement first, deploy it, then revoke the old key.

Generating your first document

A single POST /v1/documents call takes a page and a list of positioned fields, and returns the PDF as a binary stream. This example produces a hearing notice with Markdown-formatted text and a QR code, with no template required:

curl -o hearing-notice.pdf "https://api.pdfs.ecourtdate.com/v1/documents" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/pdf" \
  -d '{
    "page": { "size": "letter" },
    "fields": [
      { "type": "text",
        "content": "# Notice of Hearing\n\nState v. Avery · Case CR-2026-004821\n\nYour pretrial hearing is set for **August 15, 2026 at 9:00 AM**\nin Courtroom 3B, Summit County Courthouse.",
        "content_format": "markdown",
        "x": 72, "y": 72, "width": 360, "height": 240 },
      { "type": "barcode", "symbology": "qr",
        "content": "CR-2026-004821",
        "x": 460, "y": 72, "width": 80, "height": 80 }
    ]
  }'

Each field is placed with x and y in PDF points from the top-left corner of the page, so the text block and the QR code sit side by side. For the full walkthrough, including template creation and merge tags, see the getting started guide.

Templates and versions

Templates separate layout from data so the same document can be produced repeatedly with different values.

Step	Endpoint
Create the template shell	`POST /v1/templates`
Add a version with fields and merge tags	`POST /v1/templates/{template_id}/versions`
Publish the version	`POST /v1/templates/{template_id}/versions/{version}/publish`
Generate a document from it	`POST /v1/templates/{template_id}/generate`

The three write calls in that table (creating a template, adding a version, and publishing a version) require an X-On-Behalf-Of header identifying the person the request is made for, which the audit trail records as the acting person.

Versions are immutable and numbered. A version moves through the states draft, ready, published, and superseded. Generation targets the published version unless the request names a specific version, so publishing a new version changes what your integration produces without any change to your generate calls.

Merge tags are declared on the version with a type, a required flag, and an example value. Data that is missing or of the wrong type fails with a 422 before anything is rendered.

Conventions

Convention	Detail
Field naming	`snake_case` for request and response fields, kebab-case for path segments
Timestamps	ISO 8601 in UTC, for example `2026-08-01T17:20:04.211Z`
Pagination	Cursor based. List endpoints take `limit` (1 to 100, default 25) and an opaque `cursor`. Responses carry `next_cursor`, which is `null` on the last page. Pass a cursor back exactly as received
Idempotency	Send an `Idempotency-Key` header on POST requests to make retries safe. A replayed response carries `Idempotent-Replay: true`
Errors	RFC 9457 `application/problem+json`. An unrecognized request field returns `400 UNKNOWN_FIELD`
Throttling	Expect `429` responses under load. Retry with exponential backoff and jitter
Versioning	Versioned path segment (`/v1`). Error codes, warning codes, field types, and merge-tag types are open sets that may gain new values without notice

Limits and retention

Limit	Value
Fields per document	200
Pages per document	100
Documents per batch job	200
Download URL validity	1 hour, and URLs can be re-signed
Generated output retention	About 20 hours
Batch job status retention	48 hours

Download and store any document you need to keep. Generated outputs are not a long-term document store.

Next steps

PDFs API documentation: guides for authentication, templates, generation, errors, and warnings.
Interactive API reference: the full endpoint list with a try-it console.
OpenAPI 3.1 specification: machine-readable spec for generating clients.
eCourtDate APIs: the directory of every eCourtDate API and how their credentials differ.

What you can build with it​

Base URL​

Authentication​

Scopes​

Attributing writes​

Handling keys​

Generating your first document​

Templates and versions​

Conventions​

Limits and retention​

Next steps​