Where a submission stands

GET

/submissions/{id}

curl -X GET "https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID" \
  -H "Authorization: Bearer $VALJEAN_KEY"

const res = await fetch("https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.VALJEAN_KEY}`, },
});
console.log(await res.json());

import os, requests

res = requests.get(
    "https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID",
    headers={"Authorization": f"Bearer {os.environ['VALJEAN_KEY']}"},
)
print(res.json())

Status in plain words, the files on it, what Valjean still needs (each with a key), anonymous market progress, your broker, and how many quotes are ready.

Any key (read or read-and-submit).

Authorizations

bearerAuth
apiKeyHeader
oauth2
read

Parameters

Path Parameters

required

string format: uuid

Submission id.

Responses

200

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

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

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.

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

404

Not found, or not your agency’s (not_found). The API never says which.

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": "not_found",
    "message": "Submission not found."
  }
}

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