Quickstart

The workspace API runs the whole intake lifecycle, end to end: start a session, answer the intake conversationally, pre-fill it from PDFs you already have, generate the filled ACORD forms, download them, review the risk flags, and submit the packet to Hedge. This page walks the lifecycle twice, once with the bindly CLI and once with raw curl.

Use the CLI

Install the CLI.
Terminal window
```
npm i -g bindly-cli
```
Homebrew and a one-line install script are also available. See the CLI guide for all three options.
Sign in.
Terminal window
```
bindly login
```
bindly login uses the OAuth 2.1 device flow: it prints a short code and a URL, you approve the sign-in in Bindly, and the CLI stores a short-lived token for you. For non-interactive automation, sign in with a workspace API key instead: bindly login --api-key bsk_.... Confirm who you are with bindly whoami.
Start an intake session.
Terminal window
```
bindly session new --insured "Acme HVAC" --state TX --lob general_liability
```
This opens a fill session for the insured and returns its id.
Answer the intake, or extract it from a PDF.
Terminal window
```
bindly session answer <session-id> --message "12 employees, $2.4M revenue, no claims in 5 years"
bindly session extract <session-id> ./prior-acord-125.pdf
```
answer takes free-form text and returns the next open questions; repeat until it reports the intake is done. extract pre-fills the session from a prior ACORD, dec page, or application, so the intake only asks for the gaps.

Fill the forms and review.

bindly session fill <session-id>
bindly session download <session-id> -o ./filled
bindly session risk <session-id>

Submit to Hedge.
Terminal window
```
bindly session submit <session-id>
```
This forwards the filled forms to Hedge on your workspace’s connected account and returns the resulting Hedge submission id.

Call the API directly

Every CLI command maps to a REST endpoint under https://engine.bindly.insure. Requests are JSON over HTTPS. Authenticate with a workspace API key, sent either as a bearer token or an X-API-Key header. See Authentication for the OAuth options.

Check your credential

curl "https://engine.bindly.insure/org/me" \
  -H "Authorization: Bearer bsk_live_xxx"

Returns the workspace the key acts for: org_id, org_name, plan, auth_kind, and the key’s key_label. A 200 here means the rest of the lifecycle will authenticate.

1. Start a session

The only required field is the applicant’s insured_name. state, lobs, and naics_code are optional and help Bindly build the right application.

curl -X POST "https://engine.bindly.insure/org/sessions" \
  -H "Authorization: Bearer bsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "insured_name": "Acme HVAC",
    "state": "TX",
    "lobs": ["general_liability"],
    "naics_code": "238220"
  }'

The response contains the new session, including its session_id, which every later call uses.

2. Answer the intake conversationally

Send free-form text: batched answers, corrections, questions, or “skip that”.

curl -X POST "https://engine.bindly.insure/org/sessions/$SESSION_ID/answers" \
  -H "Authorization: Bearer bsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "12 employees, $2.4M revenue, no claims in the last 5 years"}'

The response carries an assistant message, the next open asks (each with a key, label, kind, and any options), a done flag, and progress counts (answered_count, pending_count, total_askable). Repeat until done is true or pending_count reaches zero.

3. Extract from a PDF you already have

Pre-fill the session from a prior ACORD, dec page, or application (PDF, 20MB max):

curl -X POST "https://engine.bindly.insure/org/sessions/$SESSION_ID/extract" \
  -H "Authorization: Bearer bsk_live_xxx" \
  -F "file=@./prior-acord-125.pdf"

Returns extracted_count, the extracted fields, an overall confidence, and any notes. Extracted values merge into the session, so the intake only asks for what is still missing. To attach supporting documents that ride along in the Hedge packet instead (loss runs, prior policy), use POST /org/sessions/$SESSION_ID/documents.

4. Fill the forms

curl -X POST "https://engine.bindly.insure/org/sessions/$SESSION_ID/fill" \
  -H "Authorization: Bearer bsk_live_xxx"

Generates the filled PDFs from everything collected so far and returns a per-form outcome: each entry in forms has a form_key, fields_written, a sparse_suspected hint, and any warnings. The PDF bytes are never inlined in the JSON; download them next.

5. Download the filled PDFs

curl "https://engine.bindly.insure/org/sessions/$SESSION_ID/forms/acord_125/pdf" \
  -H "Authorization: Bearer bsk_live_xxx" \
  -o acord_125.pdf

Returns the filled form as binary application/pdf. A form 404s until the fill step has produced it. The session detail’s filled_forms lists every form_key you can download.

6. Review the risk flags

curl "https://engine.bindly.insure/org/sessions/$SESSION_ID/risk-summary" \
  -H "Authorization: Bearer bsk_live_xxx"

Returns underwriter-facing flags, each with a title, detail, severity, and category. An empty list means a clean risk.

7. Submit to Hedge

curl -X POST "https://engine.bindly.insure/org/sessions/$SESSION_ID/submit" \
  -H "Authorization: Bearer bsk_live_xxx"

Bindly uploads the session’s filled forms and supporting documents to Hedge on your workspace’s connected account, finalizes the submission, and returns the Hedge submission id. Continue in the API Reference.

Where to go next

Create a workspace API key, or set up the OAuth 2.1 device flow and browser sign-in. See Authentication.

Learn every command and the --json flag in the CLI guide.