Send a submission

POST

/submissions

curl -X POST "https://api.valjeanspecialty.com/api/agent/v1/submissions" \
  -H "Authorization: Bearer $VALJEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_reference":"AMS-10442","insured":{"name":"Shem Creek Oyster Bar LLC","state":"SC","city":"Mount Pleasant"},"lines":["GL","LL"],"effective_date":"2026-12-15","class_description":"Bar and restaurant","operations":"Seafood restaurant with a full bar, closes at midnight","annual_revenue":2100000}'

const res = await fetch("https://api.valjeanspecialty.com/api/agent/v1/submissions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VALJEAN_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "client_reference": "AMS-10442",
    "insured": {
      "name": "Shem Creek Oyster Bar LLC",
      "state": "SC",
      "city": "Mount Pleasant"
    },
    "lines": [
      "GL",
      "LL"
    ],
    "effective_date": "2026-12-15",
    "class_description": "Bar and restaurant",
    "operations": "Seafood restaurant with a full bar, closes at midnight",
    "annual_revenue": 2100000
  }),
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://api.valjeanspecialty.com/api/agent/v1/submissions",
    headers={"Authorization": f"Bearer {os.environ['VALJEAN_KEY']}"},
    json={
      "client_reference": "AMS-10442",
      "insured": {
        "name": "Shem Creek Oyster Bar LLC",
        "state": "SC",
        "city": "Mount Pleasant"
      },
      "lines": [
        "GL",
        "LL"
      ],
      "effective_date": "2026-12-15",
      "class_description": "Bar and restaurant",
      "operations": "Seafood restaurant with a full bar, closes at midnight",
      "annual_revenue": 2100000
    },
)
print(res.json())

Creates a file from structured facts. Always send client_reference or an Idempotency-Key header: a retry with the same value returns the same file (200, duplicate: true) instead of creating another. The response lists what’s still needed.

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

Query Parameters

dry_run

string

Allowed values: 1 true

1 to check the request and see what would happen, without saving or sending anything.

Request Body^required

application/json

object

client_reference

string

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

insured

required

object

name

required

string

>= 1 characters <= 200 characters

state

required

string

>= 2 characters <= 40 characters

city

string

<= 100 characters

address

string

<= 200 characters

postal_code

string

/^\d{5}(-\d{4})?$/

lines

required

Array<string>

>= 1 items <= 6 items

effective_date

required

string format: date

naics

string

/^[0-9]{2,6}$/

class_description

string

<= 300 characters

operations

string

<= 4000 characters

annual_revenue

number

<= 100000000000

annual_payroll

number

<= 100000000000

tiv

number

<= 100000000000

years_in_business

integer

<= 300

target_premium

number

<= 100000000000

expiring_premium

number

<= 100000000000

prior_carrier

string

<= 200 characters

requested_limits

string

<= 500 characters

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,}$/

notes

string

<= 4000 characters

Example

{
  "client_reference": "AMS-10442",
  "insured": {
    "name": "Shem Creek Oyster Bar LLC",
    "state": "SC",
    "city": "Mount Pleasant"
  },
  "lines": [
    "GL",
    "LL"
  ],
  "effective_date": "2026-12-15",
  "class_description": "Bar and restaurant",
  "operations": "Seafood restaurant with a full bar, closes at midnight",
  "annual_revenue": 2100000
}

Responses

200

With ?dry_run=1: every check passed and nothing was saved or sent.

application/json

With ?dry_run=1: checked, nothing saved or sent. Other fields describe what would happen (the file’s insured and lines, an existing file’s id, or the quote and its subjectivities).

object

dry_run

required

boolean

valid

required

The request passed every check. A request that fails a check returns the same error it would without dry_run.

boolean

would

required

What sending it for real would do.

string

Allowed values: create return_existing request_bind

note

required

string

Example

{
  "dry_run": true,
  "valid": true,
  "would": "create"
}

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

Example

{
  "id": "6f2a1c9e-4b3d-4e8a-9c21-7d4e5f6a8b90",
  "reference": "VS-000624",
  "insured": "Shem Creek Oyster Bar LLC",
  "lines": [
    "General Liability",
    "Liquor Liability"
  ],
  "effective_date": "2026-12-15",
  "status": "Waiting on information from you",
  "stage": "needs_info",
  "received_at": "2026-11-02T14:15:11Z",
  "updated_at": "2026-11-02T14:16:02Z",
  "files": [
    "ACORD 125.pdf"
  ],
  "needs": [
    {
      "key": "hours",
      "label": "Hours of operation and closing time",
      "type": "question",
      "level": "required",
      "how": "answer",
      "answer": {
        "type": "text"
      }
    },
    {
      "key": "capacity",
      "label": "Seating / occupancy capacity",
      "type": "question",
      "level": "recommended",
      "how": "answer",
      "answer": {
        "type": "number"
      }
    },
    {
      "key": "loss_runs",
      "label": "Currently valued loss runs – 5 years",
      "type": "document",
      "level": "required",
      "how": "upload a document",
      "answer": {
        "type": "file"
      }
    }
  ],
  "quotes_ready": 0,
  "markets": {
    "reviewing": 0,
    "declined": 0,
    "quoted": 0,
    "no_response": 0,
    "total": 0,
    "presented": 0,
    "text": "Not sent to markets yet."
  },
  "broker": {
    "name": "[Broker name]",
    "email": "broker@valjeanspecialty.com"
  },
  "duplicate": false,
  "status_url": "https://valjops.vercel.app/s/EXAMPLE-status-link"
}

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."
  }
}

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 a submission

Authorizations

Parameters

Header Parameters

Example

Query Parameters

Request Bodyrequired

Example

Responses

200

Example

Headers

Example

201

Example

Headers

Example

400

Example

401

Example

403

Example

413

Example

429

Example

Headers

Example

500

Example

Request Body^required