Documents API

Generate PDF documents from your templates.

Endpoint

POST /api/v1/{org_slug}/templates/{endpoint_path}/documents

Parameters

Parameter	Type	Required	Description
`org_slug`	string	Yes	Your organization identifier
`endpoint_path`	string	Yes	Template endpoint configured in dashboard

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	Yes	Must be `application/json`
`Prefer`	No	Use `respond-async` for async mode

Request Body

Send your template data as JSON. The required fields depend on your template configuration.

Basic Example

{
  "invoice_number": "INV-001",
  "customer_name": "Acme Corp",
  "amount": 1250.00,
  "items": [
    { "name": "Widget", "quantity": 5, "price": 250.00 }
  ]
}

Special Fields

Field	Type	Description
`isTest`	boolean	Enable test mode (watermarked PDF)
`webhook`	object	Legacy webhook configuration

Response Formats

Synchronous Response

Returns the PDF binary directly:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 123456
X-Request-ID: req_abc123

[PDF binary data]

Asynchronous Response

When using Prefer: respond-async header:

{
  "request_id": "req_abc123xyz",
  "status": "queued",
  "created_at": "2024-01-01T00:00:00Z"
}

Code Examples

# Synchronous
curl -X POST https://api.doczap.app/api/v1/acme/templates/invoice/documents \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-001",
    "customer_name": "Acme Corp",
    "amount": 1250.00
  }' \
  -o invoice.pdf
 
# Asynchronous
curl -X POST https://api.doczap.app/api/v1/acme/templates/invoice/documents \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "invoice_number": "INV-001",
    "customer_name": "Acme Corp",
    "amount": 1250.00
  }'

Template Placeholders

Templates use double curly braces for placeholders:

{{invoice_number}} - Simple field replacement
{{customer.name}} - Access nested objects
{{items.0.price}} - Access array elements

Supported Syntax

Syntax	Example	Description
Simple	`{{name}}`	Direct field replacement
Nested	`{{user.email}}`	Access nested objects
Array	`{{items.0.name}}`	Access array elements

Placeholders are HTML-escaped by default for security. Unmatched placeholders remain in the output.

Page Configuration

Configure PDF output in your template settings:

Option	Values	Default	Description
`pageSize`	a3, a4, a5, letter, legal, tabloid	a4	Paper size
`orientation`	portrait, landscape	portrait	Page orientation

Limitations

Limit	Value
Request size	1 MB
Timeout (sync)	30 seconds
PDF size	50 MB
Concurrent requests	10 per API key

Error Handling

Common errors and solutions:

Status	Error	Solution
400	`invalid_template_data`	Check required fields
401	`unauthorized`	Verify API key
404	`template_not_found`	Check endpoint path
413	`payload_too_large`	Reduce request size
422	`validation_failed`	Fix data format
429	`rate_limit_exceeded`	Implement backoff
500	`internal_error`	Retry with backoff

Example error response:

{
  "error": {
    "message": "Validation failed: amount is required",
    "type": "validation_error",
    "code": "missing_required_field",
    "field": "amount"
  }
}

Authentication Error Handling