Flatten Document API

Flatten form fields in a generated PDF and convert to PDF/A-2b archival format via the Rynko flatten API.

Recommended: Upload, Extract & Regenerate

For most users, the recommended finalization workflow is Upload filled PDF -> Extract fields -> Regenerate. Use the extract-filled-fields endpoint to extract data, review it, and regenerate clean documents. The flatten API below is available for direct PDF/A-2b conversion without re-extracting.

Flatten Document

Takes a completed Klervex job ID, fetches the generated PDF from Rynko, and forwards it to the Rynko flatten endpoint for PDF/A-2b conversion.

POST /functions/v1/flatten-document

Request Body

Field	Type	Required	Description
job_id	string	Yes	The Klervex job ID (from the generate-documents response)
doc_type	string	No	Document type label (e.g., BILL_OF_LADING). Used for naming and tracking.
hash_stamp	string	No	Hash to stamp onto the flattened document
generation_history_id	string	No	When provided, the flattened download URL is saved to the generation_history record's flattened_urls JSONB field, keyed by doc_type.

Example Request

curl -X POST "https://<project-ref>.supabase.co/functions/v1/flatten-document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_ANON_KEY" \
  -d '{
    "job_id": "uuid-job-1234",
    "doc_type": "BILL_OF_LADING",
    "hash_stamp": "a1b2c3d4e5f6...",
    "generation_history_id": "uuid-hist-001"
  }'

Response (Success — 200)

{
  "download_url": "https://cdn.rynko.dev/flattened/abc123.pdf",
  "job_id": "uuid-job-1234",
  "doc_type": "BILL_OF_LADING"
}

Response Fields

Field	Type	Description
download_url	string	URL to download the flattened PDF/A-2b document
job_id	string	The Klervex job ID that was flattened
doc_type	string|null	The document type, if provided in the request

How It Works

1. Looks up the Klervex job record in Supabase to get the Rynko job ID
2. Fetches the generated PDF binary from Rynko's download URL
3. Forwards the PDF to Rynko's /v1/documents/flatten endpoint (multipart upload)
4. If generation_history_id is provided, saves the flattened URL to the generation history record
5. Returns the download URL for the flattened PDF

Error Codes

HTTP Status	Error Code	Description
400	KLV_FLAT_001	job_id is required
404	KLV_FLAT_002	Job not found
400	KLV_FLAT_003	Job has no associated Rynko job ID
400	KLV_FLAT_004	Job is not completed (includes current status in message)
400	KLV_FLAT_005	Generated document has no download URL
502	KLV_FLAT_006	Failed to download PDF from Rynko (includes HTTP status)