Skip to content
Valjean SpecialtyValjean SpecialtyValjean Developer Docs

List your submissions

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

Your agency’s submissions, most recently updated first. status takes stage names, comma-separated (new, needs_info, marketing, quoted, bound, declined, lost, closed).

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
status
string
/^[a-z_,]+$/
updated_since
string format: date-time
search
string
<= 100 characters
limit
integer
default: 25 >= 1 <= 100
offset
integer
0 <= 10000

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
total
required
integer
submissions
required
Array<object>
object
id
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

Example 

{
  "total": 1,
  "submissions": [
    {
      "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"
    }
  ]
}

Headers

Section titled “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

Section titled “400”

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

Media typeapplication/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

Section titled “401”

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

Media typeapplication/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

Section titled “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.

Media typeapplication/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."
  }
}

429

Section titled “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.

Media typeapplication/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

Section titled “Headers”
Retry-After
integer
Example 
60

Seconds to wait.

500

Section titled “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.

Media typeapplication/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."
  }
}