Core concepts
Parsers, documents, entries, validation and environments, and the IDs that connect them.
SimplyParse has a small vocabulary. Knowing how these pieces relate makes every endpoint obvious.
Parser
A parser is a reusable extraction setup for one kind of document, for example "supplier invoices" or "delivery challans". It holds:
- the fields to extract, including nested objects and lists such as line items
- the validation rules each value must pass
- settings such as the maximum page count and whether invalid entries are delivered
- its integrations: webhooks and data mappings
You build and test parsers in the dashboard. Your code then sends documents to a parser by its slug.
Templates are not endpoints
A template is a shared, read-only parser in the library. Click Use template to get your own copy, then call that copy's slug. Calling a template's slug returns parser_not_found.
Document and entry
When you send a file, SimplyParse creates a document: the uploaded file plus its processing status (pending → processing → completed or failed).
Processing a document produces one or more entries. An entry is one record of extracted data: its parsed_data, is_valid flag and validation_errors.
Most documents produce exactly one entry. A file that contains several records, such as a PDF holding twenty invoices, can produce one entry per record when you send has_multiple_entries=true. See Multiple records in one file.
Parser (slug a1b2c3)
└── Document 3c59dc04… status: completed
├── Entry 8f14e45f… is_valid: true parsed_data: {...}
└── Entry c9f0f895… is_valid: false validation_errors: [...]Validation
Extraction answers "what does the document say?" Validation answers "can my system trust it?" Rules such as required, minimum value, pattern or lookup run on every entry. Each entry reports:
is_valid:trueonly if every rule passedvalidation_errors: one item per failing field, with the rule and a message
A typical integration accepts valid entries automatically and routes the rest to a person. See Build a review queue.
Environment
Each request can carry an environment label, such as production or staging (the default is default). It is stored with the document, and only webhooks configured for that same environment receive its results. This lets staging traffic hit a staging receiver while production goes to production.
Credits
Processing is prepaid. Each document debits your balance by the parser's per-page rate × the number of pages. If the balance is too low, the request fails with insufficient_balance before any work is done. See Plans and credits.
IDs at a glance
| ID | Looks like | Where you get it | What you use it for |
|---|---|---|---|
| Parser slug | a1b2c3 | Parser → Integrations → API Details | Parse, get document, correct values |
| Parser ID | UUID | Dashboard URL: /parsers/<id> | Excel export, verifying webhook signatures |
| Document ID | UUID | data.document_id from the async endpoint; data.document_id in webhooks | Get a document |
| Entry ID | UUID | entries[].id, a webhook's data.entry_id, or data[].document_id in the sync response | Correct values, de-duplicating webhooks |
The sync response's document_id is an entry ID
In the sync parse response, each item's document_id is the ID of that entry, not of the uploaded document. It is the value to pass to Correct parsed values.