Start a session
POST https://api.129.212.147.181.sslip.io/v1/sessions
Starts a conversation for one of your end users, named by the Docgen-Subject header. Pass the user's first message (what they typed in the search box) and the session works out which form they need: a confident search match, a choice between candidates, or clarifying questions, and when no form fits, an AI interview drafts a custom document. Forms are internal: you never name one.
The response is a turn: reply is the assistant's first message and session the session after it. Keep calling POST /v1/sessions/{session}/messages until session.phase is ready, then run one of session.actions.
Headers
Bearer dg_test_… or Bearer dg_live_…
Your reference for the end user (a user ID, a hash; never an email).
A session is bound to the subject it was created with, and every call
on it must send the same value or it is 404. Set it from your own
login, never from what the browser sent. Required to create and list
sessions unless your organisation has subjects turned off.
Retrying with the same key and body returns the original response. Kept 24 hours.
Body
The end user's first message, e.g. what they typed in a search box. Omit it and the reply asks what they need.
US state as ISO 3166-2 (US-FL). Optional; otherwise it is detected from the message or asked.
Delete the session this long after it starts, up to the default of 7 days. Omit for the default.
Up to 20 keys of your own, echoed back and shown in logs. Don't put personal data here.
Returns
201 Created: a Turn object. The first turn.
Errors
| Status | Code | What to do |
|---|---|---|
| 422 | subject_required | Send Docgen-Subject, set from your own login (never from what the browser sent). |
| 422 | parameter_invalid | error.fields names the bad parameter (message, settings, lifetime_seconds, metadata). |
| 422 | jurisdiction_invalid | Use a state code such as US-FL. |
| 503 | provider_unavailable | Finding a form by conversation needs a model; live keys get this until one is configured. |
Any endpoint can also return the common errors (bad key, rate limit, idempotency).