What underwriters will ask about

GET

/submissions/{id}/flags

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

const res = await fetch("https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/flags", {
  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/flags",
    headers={"Authorization": f"Bearer {os.environ['VALJEAN_KEY']}"},
)
print(res.json())

Things on this file underwriters usually question (payroll not split by class, whether subcontractors are insured, gaps or stale loss runs, large losses without detail), each with a plain question to answer now through the answers endpoint. Read-only, and drawn only from your own file.

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

submission_id

required

string format: uuid

flags

required

Array<object>

object

key

required

What kind of question, e.g. lump_sum_payroll, subs_insurance_unanswered, uninsured_subs, exposure_unrealistic, loss_runs_gap, loss_runs_stale, large_loss_undocumented.

string

severity

required

High: underwriters usually won’t quote until it’s answered.

string

Allowed values: high medium

title

required

string

detail

required

Why it stands out, from the facts on your file.

string

question

required

The question to answer ahead of time.

string

note

required

string

Example

{
  "submission_id": "6f2a1c9e-4b3d-4e8a-9c21-7d4e5f6a8b90",
  "flags": [
    {
      "key": "loss_runs_gap",
      "severity": "high",
      "title": "Loss runs cover 3 of the 5 years needed",
      "detail": "Loss runs on file cover 2023 to 2026. Markets want 5 years.",
      "question": "Can you send currently valued loss runs for the two earlier years, or confirm the insured had no coverage then?"
    }
  ],
  "note": "Underwriters will likely ask about these. Answering them now (POST /submissions/{id}/answers) usually saves a round trip."
}

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