Create a Parser

Endpoint: POST /v1/parsers. Reference for creating a new parser template programmatically.

`POST /v1/parsers`

Creates a new parser template. If fields is omitted or empty, a blank parser container is created.

Body Parameters

Parameter	Type	Required	Description
`name`	`string`	✅	Unique name for the parser (max 100 chars).
`description`	`string`	❌	Human-readable description.
`result_mode`	`string`	❌	`one_per_file` (default) or `one_per_page`. Maps to dashboard One document per file / One document per page under How are your files organized?.
`fields`	`array`	❌	List of field definitions containing `name` (required), `type` (optional), and `description` (optional). If omitted with a `document_type`, the preconfigured fields for that type are used.
`document_type`	`string`	❌	Document type slug (e.g. `invoices`, `receipts`, `purchase-orders`). When provided without explicit `fields`, seeds the parser with a standard field configuration for that type. See the document types reference for valid values.

curl -X POST https://api.perfectparser.com/v1/parsers \
  -H "X-API-Key: pp_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Invoice Parser", "result_mode": "one_per_file"}'

Response 201 Created

{
  "parser": {
    "parser_id": "prs_999",
    "name": "Invoice Parser",
    "description": null,
    "result_mode": "one_per_file",
    "document_type": null,
    "schema": {},
    "fields": {},
    "has_sample_file": false,
    "created_at": "2026-06-20T10:00:00.000Z",
    "updated_at": "2026-06-20T10:00:00.000Z"
  }
}

Document Types

The following slugs are valid values for document_type:

Slug	Label
`invoices`	Invoice
`receipts`	Receipt
`purchase-orders`	Purchase Order
`bank-statements`	Bank Statement
`contracts`	Contract
`bills-of-lading`	Bill of Lading
`delivery-notes`	Delivery Note
`payslips`	Payslip
`insurance-policies`	Insurance Policy
`tax-forms`	Tax Form
`medical-records`	Medical Record
`utility-bills`	Utility Bill

Common Error Responses

HTTP Status	Error Code	Description
`400`	`INVALID_PAYLOAD`	Request body validation failed or malformed JSON.
`401`	`UNAUTHORIZED`	Invalid or missing API key.
`409`	`CONFLICT`	A parser with this name already exists.

POST /v1/parsers

Document Types

Common Error Responses

On this page

`POST /v1/parsers`