`POST /v1/parsers/:id/detect-fields`

Runs AI-powered layout detection on a sample document and automatically generates a JSON Schema for the parser.

Generating a schema with AI costs 1 credit per page of the sample document. Future manual modifications to the schema are free.

By default, if the parser already has a schema configured, this request returns SCHEMA_ALREADY_EXISTS. Set replace_existing_schema to true to overwrite.

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	✅	The unique ID of the parser.

Mode A — Upload sample file (recommended)

Upload a sample file and detect fields in one request using multipart/form-data.

Body Parameters (multipart)

Parameter	Type	Required	Description
`file`	`file`	✅	Sample PDF or image.
`prompt`	`string`	❌	Optional hints (e.g. "focus on line items").
`replace_existing_schema`	`string`	❌	`"true"` to overwrite an existing schema.

curl -X POST https://api.perfectparser.com/v1/parsers/prs_999/detect-fields \
  -H "X-API-Key: pp_live_your_secret_key" \
  -F "file=@sample_invoice.pdf"

Mode B — Re-run on existing sample (JSON)

If you already uploaded a sample via Mode A, re-run detection without re-uploading:

Body Parameters (JSON)

Parameter	Type	Required	Description
`sample_file_id`	`string`	✅	From a previous detect-fields response or `GET /v1/parsers/:id`.
`prompt`	`string`	❌	Optional hints.
`replace_existing_schema`	`boolean`	❌	Set to `true` to overwrite (default: `false`).

curl -X POST https://api.perfectparser.com/v1/parsers/prs_999/detect-fields \
  -H "X-API-Key: pp_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"sample_file_id": "smp_123", "replace_existing_schema": true}'

Where to get sample_file_id

Returned in every successful detect-fields response (sample_file_id field).
Available on Get Parser as parser.sample_file_id when a sample has been uploaded.

Response 200 OK

{
  "parser_id": "prs_999",
  "sample_file_id": "smp_123",
  "schema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string", "description": "" },
      "total_amount": { "type": "number", "description": "" }
    },
    "required": ["invoice_number", "total_amount"]
  },
  "credits_used": 3
}

Common Error Responses

HTTP Status	Error Code	Description
`400`	`INVALID_PAYLOAD`	Missing file or `sample_file_id`, or malformed body.
`400`	`SCHEMA_ALREADY_EXISTS`	Schema exists and `replace_existing_schema` was not set.
`401`	`UNAUTHORIZED`	Invalid or missing API key.
`402`	`INSUFFICIENT_CREDITS`	Account balance too low.
`404`	`RESOURCE_NOT_FOUND`	Sample file not found.
`404`	`PARSER_NOT_FOUND`	Parser not found or belongs to another account.

Detect Fields

`POST /v1/parsers/:id/detect-fields`

Mode A — Upload sample file (recommended)

Mode B — Re-run on existing sample (JSON)

Common Error Responses

On this page