Document Generation

Generate documents from templates by providing merge data. This guide covers single document generation, output formats, and status tracking.

Generating a Document

Provide a template ID and merge data to generate a document.

cURL

curl -X POST "https://api.propper.ai/v1/docgen/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_abc123",
    "mergeData": {
      "customerName": "Acme Corp",
      "invoiceNumber": "INV-2024-001",
      "lineItems": [
        { "description": "Consulting", "amount": "$5,000" },
        { "description": "Development", "amount": "$10,000" }
      ]
    },
    "outputFormat": "PDF"
  }'

JavaScript

const response = await fetch('https://api.propper.ai/v1/docgen/documents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tmpl_abc123',
    mergeData: {
      customerName: 'Acme Corp',
      invoiceNumber: 'INV-2024-001',
      lineItems: [
        { description: 'Consulting', amount: '$5,000' },
        { description: 'Development', amount: '$10,000' },
      ],
    },
    outputFormat: 'PDF',
  }),
});

const document = await response.json();

Response:

{
  "id": "doc_xyz789",
  "templateId": "tmpl_abc123",
  "status": "GENERATED",
  "outputFormat": "PDF",
  "createdAt": "2024-01-15T10:01:00Z"
}

Pass repeating data (such as lineItems above) as an array of objects. When the template declares that field as a collection, each array element is rendered once by the template's repeating section, and the array is validated against the declared item types before the document is produced. See Collections in the Template Management guide.

Output Formats

Format	Description
PDF	Portable Document Format (recommended)
HTML	HTML document

Checking Document Status

Document generation may take a moment for complex templates. Poll the status endpoint to track progress.

curl "https://api.propper.ai/v1/docgen/documents/{documentId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Status Flow

Status	Description
DRAFT	Document created, generation not started
GENERATING	Generation in progress
GENERATED	Document ready for download
FAILED	Generation failed (check error details)

Downloading a Document

Once a document reaches GENERATED status, download it.

cURL

curl "https://api.propper.ai/v1/docgen/documents/{documentId}/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o output.pdf

JavaScript

const response = await fetch(`https://api.propper.ai/v1/docgen/documents/${documentId}/download`, {
  headers: { Authorization: `Bearer ${token}` },
});

const buffer = Buffer.from(await response.arrayBuffer());
await fs.writeFile('./output.pdf', buffer);

Listing Documents

Retrieve a paginated list of generated documents.

curl "https://api.propper.ai/v1/docgen/documents?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "data": [
    {
      "id": "doc_xyz789",
      "templateId": "tmpl_abc123",
      "status": "GENERATED",
      "outputFormat": "PDF",
      "createdAt": "2024-01-15T10:01:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1
  }
}

Error Handling

When generation fails, the document status will be FAILED and include error details:

{
  "id": "doc_xyz789",
  "status": "FAILED",
  "error": {
    "code": "MERGE_DATA_MISSING",
    "message": "Required merge field 'customerName' not provided"
  }
}

Common error codes:

Code	Description
MERGE_DATA_MISSING	Required template placeholder not provided
TEMPLATE_NOT_FOUND	Template ID does not exist or is archived
GENERATION_TIMEOUT	Document generation exceeded time limit
INVALID_FORMAT	Unsupported output format requested