Send documents and a description

POST

/intake

curl -X POST "https://api.valjeanspecialty.com/api/agent/v1/intake" \
  -H "Authorization: Bearer $VALJEAN_KEY" \
  -F "narrative=Seafood restaurant with a full bar in Mount Pleasant" \
  -F "state=SC" -F "lines=GL,LL" -F "client_reference=INT-1" \
  -F "files=@ACORD-125.pdf;type=application/pdf"

import fs from "node:fs";

const form = new FormData();
form.append("files", new Blob([await fs.promises.readFile("loss-runs.pdf")], { type: "application/pdf" }), "loss-runs.pdf");
form.append("narrative", "Seafood restaurant with a full bar in Mount Pleasant");
const res = await fetch("https://api.valjeanspecialty.com/api/agent/v1/intake", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VALJEAN_KEY}` },
  body: form,
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://api.valjeanspecialty.com/api/agent/v1/intake",
    headers={"Authorization": f"Bearer {os.environ['VALJEAN_KEY']}"},
    files={"files": ("loss-runs.pdf", open("loss-runs.pdf", "rb"), "application/pdf")},
)
print(res.json())

Starts a file from documents plus a few sentences. Valjean reads the documents with AI and a broker confirms the details. multipart/form-data with “files” (up to 5, 4 MB in total) and the fields below (lines comma-separated), or JSON with the same fields and no files.

Needs a read-and-submit key and an agency with a signed broker agreement.

Authorizations

bearerAuth
apiKeyHeader
oauth2
submit

Parameters

Header Parameters

Idempotency-Key

string

/^[\w.:-]{1,80}$/

Your own id for this request (up to 80 letters, numbers, . _ : -). Used as client_reference when the body has none; a retry with the same key returns the first file (200, duplicate: true). If both are sent they must match.

Example

AMS-10442

Request Body^required

object

files

Up to 5 files, 4 MB in total. PDF, images, Word, Excel, CSV or text.

Array<string>

<= 5 items

narrative

string

<= 8000 characters

insured_name

string

<= 200 characters

state

string

lines

Comma-separated, e.g. GL,LL.

string

effective_date

string format: date

client_reference

string

contact_email

string format: email

Example

{
  "narrative": "Family-owned seafood restaurant with a bar in Folly Beach, open 11 to 11.",
  "state": "SC",
  "lines": "GL,LL",
  "client_reference": "INT-1"
}

object

narrative

string

>= 1 characters <= 8000 characters

client_reference

string

/^[\w.:-]{1,80}$/

insured_name

string

>= 1 characters <= 200 characters

state

string

>= 2 characters <= 40 characters

lines

Array<string>

<= 6 items

effective_date

string format: date

contact_email

string format: email

/^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/

Example ^generated

{
  "narrative": "example",
  "client_reference": "example",
  "insured_name": "example",
  "state": "example",
  "lines": [
    "example"
  ],
  "effective_date": "2026-04-15",
  "contact_email": "hello@example.com"
}

Responses

200

A retry with the same client_reference or Idempotency-Key: the first file, with duplicate: true. Nothing new is created.

application/json

object

required

string format: uuid

reference

required

Valjean reference, e.g. VS-000624.

string

insured

required

string

lines

required

Line names, e.g. “General Liability”.

Array<string>

effective_date

required

string | null format: date

status

required

Plain-English status you can show as is.

string

stage

required

string

Allowed values: new needs_info marketing quoted bound declined lost closed

received_at

required

string format: date-time

updated_at

required

string format: date-time

files

required

File names on the submission.

Array<string>

needs

required

What’s still open, each with a key. Empty once the file is closed.

Array<object>

object

key

required

string

label

required

string

type

required

Document, field, question, photo, or “requested” (an item your broker asked for).

string

level

required

string

Allowed values: required recommended

how

required

“answer”, “upload a document” or “answer or upload”.

string

answer

required

object

type

required

How to answer. “file” means upload a document instead.

string

Allowed values: text number money percent yes_no choice date file

options

For type “choice”: the allowed answers.

Array<string>

quotes_ready

required

Quotes your broker has presented.

integer

markets

required

Anonymous counts: market names appear only on presented quotes.

object

reviewing

required

integer

declined

required

integer

quoted

required

integer

no_response

required

integer

total

required

Markets the file has been sent to.

integer

presented

required

Quotes your broker has presented to you.

integer

text

required

One plain sentence, e.g. “With 4 markets: 3 quoted, 1 declined.”

string

broker

required

Any of:

object
null

object

name

required

string | null

email

required

string format: email

duplicate

required

True when client_reference (or the Idempotency-Key header) matched an existing file: that file is returned with 200 and nothing new is created.

boolean

status_url

A private status page you can share with the producer. Treat it like a password. Returned when the file is created; a duplicate doesn’t make another link.

string format: uri

documents

required

Array<object>

object

document_id

required

string format: uuid

file_name

required

string

doc_type

required

Detected or given document type, e.g. acord_125, loss_runs, sov, other.

string

note

string

duplicate

Only on /documents/complete when the upload was already recorded.

boolean

note

string

Example

{
  "stage": "new",
  "needs": [
    {
      "level": "required",
      "answer": {
        "type": "text"
      }
    }
  ]
}

Headers

RateLimit-Policy

string

Example

"per-key";q=120;w=60

The rate limit for this key, as an IETF RateLimit-Policy: 120 requests (q) per 60-second window (w), counted across all of Valjean’s servers. Over it, you get 429 with Retry-After.

201

application/json

object

required

string format: uuid

reference

required

Valjean reference, e.g. VS-000624.

string

insured

required

string

lines

required

Line names, e.g. “General Liability”.

Array<string>

effective_date

required

string | null format: date

status

required

Plain-English status you can show as is.

string

stage

required

string

Allowed values: new needs_info marketing quoted bound declined lost closed

received_at

required

string format: date-time

updated_at

required

string format: date-time

files

required

File names on the submission.

Array<string>

needs

required

What’s still open, each with a key. Empty once the file is closed.

Array<object>

object

key

required

string

label

required

string

type

required

Document, field, question, photo, or “requested” (an item your broker asked for).

string

level

required

string

Allowed values: required recommended

how

required

“answer”, “upload a document” or “answer or upload”.

string

answer

required

object

type

required

How to answer. “file” means upload a document instead.

string

Allowed values: text number money percent yes_no choice date file

options

For type “choice”: the allowed answers.

Array<string>

quotes_ready

required

Quotes your broker has presented.

integer

markets

required

Anonymous counts: market names appear only on presented quotes.

object

reviewing

required

integer

declined

required

integer

quoted

required

integer

no_response

required

integer

total

required

Markets the file has been sent to.

integer

presented

required

Quotes your broker has presented to you.

integer

text

required

One plain sentence, e.g. “With 4 markets: 3 quoted, 1 declined.”

string

broker

required

Any of:

object
null

object

name

required

string | null

email

required

string format: email

duplicate

required

True when client_reference (or the Idempotency-Key header) matched an existing file: that file is returned with 200 and nothing new is created.

boolean

status_url

A private status page you can share with the producer. Treat it like a password. Returned when the file is created; a duplicate doesn’t make another link.

string format: uri

documents

required

Array<object>

object

document_id

required

string format: uuid

file_name

required

string

doc_type

required

Detected or given document type, e.g. acord_125, loss_runs, sov, other.

string

note

string

duplicate

Only on /documents/complete when the upload was already recorded.

boolean

note

string

Example

{
  "stage": "new",
  "needs": [
    {
      "level": "required",
      "answer": {
        "type": "text"
      }
    }
  ]
}

Headers

RateLimit-Policy

string

Example

"per-key";q=120;w=60

The rate limit for this key, as an IETF RateLimit-Policy: 120 requests (q) per 60-second window (w), counted across all of Valjean’s servers. Over it, you get 429 with Retry-After.

400

Fix the request and send it again (invalid_request, invalid_json).

application/json

object

error

required

object

code

required

Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.

string

message

required

Plain-English explanation you can show a person.

string

issues

Validation problems, as “field: problem” (400 invalid_request only).

Array<string>

Example

{
  "error": {
    "code": "invalid_request",
    "message": "Check the request.",
    "issues": [
      "insured.state: Too small: expected string to have >=2 characters"
    ]
  }
}

401

Key or token missing, wrong, expired or revoked (unauthorized). Don’t retry: get a new key or sign in again.

application/json

object

error

required

object

code

required

Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.

string

message

required

Plain-English explanation you can show a person.

string

issues

Validation problems, as “field: problem” (400 invalid_request only).

Array<string>

Example

{
  "error": {
    "code": "unauthorized",
    "message": "This API key isn't valid. Ask your Valjean broker for a new one."
  }
}

403

Not allowed: read_only (a read key tried to submit), agency_not_active (no signed broker agreement), not_offered (instant quotes are off), forbidden (API access off for the agency). Don’t retry.

application/json

object

error

required

object

code

required

Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.

string

message

required

Plain-English explanation you can show a person.

string

issues

Validation problems, as “field: problem” (400 invalid_request only).

Array<string>

Example

{
  "error": {
    "code": "read_only",
    "message": "This key can read only. Ask your Valjean broker for a key that can submit."
  }
}

413

Body or file too large (too_large): JSON bodies up to 64 KB, direct uploads 4 MB, upload links 25 MB.

application/json

object

error

required

object

code

required

Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.

string

message

required

Plain-English explanation you can show a person.

string

issues

Validation problems, as “field: problem” (400 invalid_request only).

Array<string>

Example

{
  "error": {
    "code": "too_large",
    "message": "Files over 4 MB need an upload link."
  }
}

415

File type not accepted (unsupported_type): PDF, images, Word, Excel, CSV or text.

application/json

object

error

required

object

code

required

Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.

string

message

required

Plain-English explanation you can show a person.

string

issues

Validation problems, as “field: problem” (400 invalid_request only).

Array<string>

Example

{
  "error": {
    "code": "unsupported_type",
    "message": "Send PDF, image, Word, Excel, CSV or text files."
  }
}

429

Too many requests (rate_limited): 120 a minute per key, 30 a minute per IP on public endpoints, counted across all of Valjean’s servers. Wait Retry-After seconds.

application/json

object

error

required

object

code

required

Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.

string

message

required

Plain-English explanation you can show a person.

string

issues

Validation problems, as “field: problem” (400 invalid_request only).

Array<string>

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in a minute."
  }
}

Headers

Retry-After

integer

Example

Seconds to wait.

500

Something went wrong on Valjean’s side (server_error). Safe to retry later; creates are idempotent with client_reference or an Idempotency-Key header.

application/json

object

error

required

object

code

required

Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.

string

message

required

Plain-English explanation you can show a person.

string

issues

Validation problems, as “field: problem” (400 invalid_request only).

Array<string>

Example

{
  "error": {
    "code": "server_error",
    "message": "Something went wrong. Try again shortly."
  }
}

Send documents and a description

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Example

Example generated

Responses

200

Example

Headers

Example

201

Example

Headers

Example

400

Example

401

Example

403

Example

413

Example

415

Example

429

Example

Headers

Example

500

Example

Request Body^required

Example ^generated