Skip to content
Valjean SpecialtyValjean SpecialtyValjean Developer Docs

For AI agents

If you’re building an AI agent on Valjean, or wiring Valjean into an assistant, follow this order. Each step names the MCP tool and the REST call that do the same thing.

# Step MCP tool REST
1 Check the key works whoami GET /me
2 Will Valjean likely place it check_appetite POST /appetite
3 What the class needs, before a file exists get_requirements POST /requirements
4 Send the file (confirm with the user first) create_submission or send_documents POST /submissions or POST /intake
5 What underwriters will ask underwriter_questions GET /submissions/{id}/flags
6 Answer what’s needed (confirm first) answer_questions PATCH /submissions/{id}/answers
7 Add documents (confirm first) add_document, get_upload_link + finish_upload POST …/documents, upload link
8 Follow it whats_new, get_submission GET /events or webhooks, GET /submissions/{id}
9 Quotes and paper list_quotes, list_documents, get_document_link GET …/quotes, GET …/documents
10 Ask to bind (confirm the exact quote first) request_bind, list_bind_requests POST …/bind-request
11 After binding list_policies, get_policy, list_invoices GET /policies, GET /invoices

Hard rules

Section titled “Hard rules”
  • Never fill a gap with a guess. Only send facts the user gave you or that are in their documents. If something is missing, ask; if nobody knows, leave it out.
  • Confirm before anything that sends. Creating a file, answers, documents, bind requests and instant-quote asks all need the user’s go-ahead.
  • One file per risk. Send client_reference (or an Idempotency-Key header) on every create, so a retry never makes a second file.
  • Answer once. Use the key on each item in needs; one answer fills every market that asks it. The user’s own words can go in message.
  • Get ahead of underwriters. After creating a file, check step 5 and offer to answer those questions with the user.
  • Indications, not promises. Appetite answers and instant quotes are indications. Quotes count once your broker presents them.
  • Binding needs a person. A bind request is the agent’s written instruction. Your broker confirms with the market and sends the binder.
  • Respect the errors. Stop on 403, fix the request on 400 and 409, wait Retry-After on 429. See Errors.