Document names

Any document name is accepted — there is no fixed catalogue to validate against.

Both POST /candidates’s documents field and POST /candidates/{id}/documents accept ANY name. There used to be a fixed nine-entry catalogue this API rejected names outside of; that restriction is gone — the conversation engine now asks about any collectible name you give it exactly as it would a catalogue entry.

Nine names are still special, in that the engine recognises them by category and can ask a more specific question about them:

• DBS
• Passport
• Proof of Address
• Right to Work
• Driving Licence
• Social Work England
• NMC Registration
• HCPC Registration
• Training Certificate

Omit documents entirely on create and the candidate gets the default five-item checklist — the first five of the nine names above.

What a catalogue name gets you#

• The bot recognises the document CATEGORY (a DBS variant, a driving licence, …) and matches an upload against it more precisely.
• For some of these, the bot first asks a possession question ("do you have a current one?") before requesting the upload. Which documents get the question may change, so treat it as something that may happen rather than a fixed list.
• A hard-required catalogue document the candidate says they do NOT have moves the checklist item to awaiting_recruiter_action instead of staying open indefinitely.

What a custom name gets you#

• The bot asks for it by the exact name you gave, with no possession question first.
• An upload the bot cannot confidently classify against a custom name goes to needs_review rather than being auto-accepted or auto-rejected.

Name handling#

• Names are trimmed and deduplicated case-insensitively against the candidate’s existing checklist.
• A name that reads as a CV or a reference (rather than a document to collect) is dropped, not seeded — references are requested through the separate references endpoints, never through documents.
• Documents are asked about in a fixed priority order (DBS first, then the rest) regardless of the order you sent them in.