Skip to content
Valjean SpecialtyValjean SpecialtyValjean Developer Docs

Answer what's needed, once for every market (POST form)

POST
/submissions/{id}/answers
curl -X POST "https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/answers" \
  -H "Authorization: Bearer $VALJEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"answers":[{"key":"hours","value":"11am to midnight, 7 days"}],"message":"Seats 120. Payroll is $640K and they've been open 12 years."}'

Same as PATCH /submissions/{id}/answers; kept for clients that can’t send PATCH.

Answers open items by key; one answer fills every market that asks the same thing. fields only fill blanks: anything Valjean already has is kept. Answers that don’t fit the item’s answer type come back in rejected and aren’t saved. Or send message: the answers in plain sentences, and Valjean maps them to the open items (from_message shows what it understood; anything sent by key wins). A broker confirms everything. POST to the same path works too.

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Submission id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
answers
Array<object>
default: <= 50 items
object
key
required
string
/^[a-z0-9_]{1,80}$/
value
required
string
>= 1 characters <= 4000 characters
fields
object
annual_revenue
number
<= 100000000000
annual_payroll
number
<= 100000000000
tiv
number
<= 100000000000
years_in_business
integer
<= 300
subcontractor_costs
number
<= 100000000000
naics_code
string
/^[0-9]{2,6}$/
class_description
string
<= 300 characters
operations_description
string
<= 4000 characters
requested_limits
string
<= 500 characters
prior_carrier
string
<= 200 characters
expiring_premium
number
<= 100000000000
target_premium
number
<= 100000000000
message
string
>= 1 characters <= 4000 characters

Example 

{
  "answers": [
    {
      "key": "hours",
      "value": "11am to midnight, 7 days"
    }
  ],
  "message": "Seats 120. Payroll is $640K and they've been open 12 years."
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
answered
required

Keys that were recorded.

Array<string>
unmatched
required

Keys not asked on this file (still saved in the file note).

Array<string>
rejected
required

Answers that didn’t fit the expected type: not saved.

Array<object>
object
key
required
string
reason
required
string
upload_instead
required

Keys that need a document upload rather than text.

Array<string>
fields_filled
required

Fields that were blank and are now filled.

Array<string>
fields_kept
required

Fields Valjean already had: kept, not overwritten.

Array<string>
from_message

Only when message was sent: what Valjean understood from it.

object
answers
required

Answers read from message (keys you also sent directly are left to yours).

Array<object>
object
key
required
string
value
required
string
fields
required

Fields read from message.

Array<string>
not_understood
required

Sentences or values that couldn’t be mapped. Send them by key, or reword.

Array<string>
note
required
string
needs
required

What’s still open after these answers.

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>

Example 

{
  "answered": [
    "hours",
    "capacity"
  ],
  "unmatched": [],
  "rejected": [],
  "upload_instead": [],
  "fields_filled": [
    "annual_payroll",
    "years_in_business"
  ],
  "fields_kept": [],
  "from_message": {
    "answers": [
      {
        "key": "capacity",
        "value": "120"
      }
    ],
    "fields": [
      "annual_payroll",
      "years_in_business"
    ],
    "not_understood": []
  },
  "note": "Answers go to your broker to confirm. Anything already on file was kept.",
  "needs": []
}

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

404

Section titled “404”

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

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

409

Section titled “409”

The file’s state doesn’t allow it: closed, not_open, quote_expired, already_requested, not_withdrawable (the bind request already went to the market: call your broker), no_instant_market, limit, or ai_off (plain-sentence answers aren’t switched on; send answers by key). Don’t retry the same request.

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": "closed",
    "message": "This submission is closed."
  }
}

413

Section titled “413”

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

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": "too_large",
    "message": "Files over 4 MB need an upload link."
  }
}

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

503

Section titled “503”

A service Valjean relies on didn’t answer (ai_unavailable: the message couldn’t be read just now). Retry shortly, or send answers by key.

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": "ai_unavailable",
    "message": "Couldn't read the message just now. Try again, or send answers by key."
  }
}