Extract Filled Fields API

Upload a filled PDF to extract form field values and map them to shipment data paths. This is the recommended way to finalize documents in Klervex — extract the data from filled PDFs, then regenerate clean documents.

info

Extraction is instant — field values are read directly from the PDF form data using pdf-lib, not inferred by AI. Confidence is always 100%.

Extract Filled Fields

Reads form field values from a filled PDF and returns structured data mapped to shipment fields. Optionally merges the extracted values into the shipment automatically.

POST /functions/v1/extract-filled-fields

Request

Send the filled PDF as a multipart form upload.

Field	Type	Required	Description
file	File	Yes	The filled PDF file
doc_type	string	Yes	The document type key (e.g., BILL_OF_LADING). Must be a supported type.
shipment_id	string	No	Shipment UUID. When provided, extracted values are merged into the shipment data.
auto_merge	string	No	Set to "false" to disable auto-merge. Default: true (merge is enabled unless explicitly set to "false").

Example Request

curl -X POST "https://<project-ref>.supabase.co/functions/v1/extract-filled-fields" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "apikey: YOUR_ANON_KEY" \
  -F "[email protected]" \
  -F "doc_type=BILL_OF_LADING" \
  -F "shipment_id=uuid-1234"

Response (Success — 200)

{
  "extracted_fields": {
    "blNumber": "MAEU-HAM-2026-04281",
    "vesselName": "MAERSK SINGAPORE",
    "voyageNumber": "042W",
    "portOfLoading": "USLAX",
    "emptyField": ""
  },
  "mapped_data": {
    "route.vessel_name": "MAERSK SINGAPORE",
    "bl_data.bl_number": "MAEU-HAM-2026-04281"
  },
  "unmapped_fields": {
    "customField": "some value"
  },
  "field_count": 11,
  "filled_count": 8,
  "empty_count": 3,
  "merge_result": {
    "merged": true,
    "updatedPaths": [
      "route.vessel_name",
      "bl_data.bl_number"
    ]
  }
}

Response Fields

Field	Type	Description
extracted_fields	object	Flat key-value map of all form field names to their values. Empty fields have value "".
mapped_data	object	Key-value map of shipment data paths to extracted values (only non-empty fields).
unmapped_fields	object	Fields with values that could not be mapped to a known shipment data path. Only present if there are unmapped fields.
field_count	number	Total text form fields found in the PDF
filled_count	number	Fields with non-empty values
empty_count	number	Fields that were still empty
merge_result	object	Only present when shipment_id is provided. Contains merged: true and updatedPaths array listing which shipment data paths were updated.

Identity Validation

Klervex embeds hidden form fields in generated PDFs to prevent accidental cross-shipment data merging. When uploading a filled PDF:

• If the PDF was generated for a different shipment than the shipment_id parameter, the request is rejected with KLV_VAL_007.
• If the PDF's embedded document type does not match the doc_type parameter, the request is rejected with KLV_VAL_008.

These hidden fields (_klervex_shipment_id, _klervex_doc_type, _klervex_shipment_ref) are stripped from the extracted data and never returned in the response.

Error Codes

HTTP Status	Error Code	Description
400	KLV_VAL_001	file is required
400	KLV_VAL_002	doc_type is required
400	KLV_VAL_003	Only PDF files are supported
400	KLV_VAL_004	Unknown doc_type. Response includes the list of supported types.
400	KLV_VAL_005	Failed to parse PDF — file is corrupted or not a valid PDF
400	KLV_VAL_006	PDF contains no form fields. Upload a PDF generated with fillable form fields.
400	KLV_VAL_007	Shipment mismatch — the uploaded PDF was generated for a different shipment. Response includes both the expected and actual shipment IDs.
400	KLV_VAL_008	Document type mismatch — the uploaded PDF is a different document type than the doc_type parameter.
404	KLV_SHIP_004	Shipment not found (when shipment_id is provided)
500	KLV_SYS_001	Failed to update shipment data

Error Response Example

{
  "error": {
    "code": "KLV_VAL_007",
    "message": "Document belongs to a different shipment (ref: SHP-2026-001). Expected shipment uuid-1234 but the PDF was generated for shipment uuid-5678."
  }
}

Usage Notes

• Empty fields are included in extracted_fields with value "" so you can see which fields were not filled.
• Only text form fields are extracted. Checkboxes, dropdowns, and other field types are skipped.
• When auto_merge is enabled (the default), both empty/missing fields and changed fields in the shipment are updated with the extracted values.
• After merging, call generate-documents to regenerate clean documents with the complete data.