Skip to content
Valjean SpecialtyValjean SpecialtyValjean Developer Docs

Will Valjean likely place it

POST
/appetite
curl -X POST "https://api.valjeanspecialty.com/api/agent/v1/appetite" \
  -H "Authorization: Bearer $VALJEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lines":["GL","LL"],"state":"SC","description":"seafood restaurant with a full bar"}'

Checks Valjean’s appetite on file for the lines, state and class. Counts only markets Valjean can reach (appointed, or at most a possible fit while an appointment is under way). Never names a market. Anything but a good fit includes how_to_send.

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

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
lines
required
Array<string>
>= 1 items <= 6 items
state
required
string
>= 2 characters <= 40 characters
naics
string
/^[0-9]{2,6}$/
description
string
<= 300 characters
target_premium
number
<= 1000000000
tiv
number
<= 100000000000

Example 

{
  "lines": [
    "GL",
    "LL"
  ],
  "state": "SC",
  "description": "seafood restaurant with a full bar"
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
fit
required

“unknown” means no appetite is on file for these lines yet: fall back to your own guidance.

string
Allowed values: good possible unlikely unknown
appetite_on_file
required
boolean
headline
required

One sentence you can show as is.

string
market_count
required

Markets on file that could write it, capped at 5. Market names are never returned.

integer
market_count_label
required

E.g. “2 markets”, “5+ markets”, “Not on file yet”.

string
lines
required
Array<object>
object
line
required

Line code.

string
fit
required
string
Allowed values: good possible unlikely
notes
required
Array<string>
needs
required

What Valjean will need for this risk, in plain words.

Array<string>
class_matched
required

The class Valjean matched the risk to, if any.

string | null
state
required

Two-letter state code.

string
unknown_lines

Lines in the request Valjean didn’t recognise.

Array<string>
how_to_send

Present whenever the fit isn’t “good”: a broker reviews every submission, including ones outside the appetite on file.

object
email
required

Where to email the risk instead.

string format: email
include
required

What to include in that email.

Array<string>
note
required
string

Example 

{
  "fit": "possible",
  "appetite_on_file": true,
  "headline": "Possible fit in SC: a broker will confirm.",
  "market_count": 2,
  "market_count_label": "2 markets",
  "lines": [
    {
      "line": "GL",
      "fit": "good"
    },
    {
      "line": "LL",
      "fit": "possible"
    }
  ],
  "notes": [],
  "needs": [
    "Annual sales split: food vs liquor",
    "Hours of operation and closing time"
  ],
  "class_matched": "Hospitality",
  "state": "SC",
  "how_to_send": {
    "email": "submissions@valjeanspecialty.com",
    "include": [
      "Insured name, address and a short description of operations",
      "Five years of currently valued loss runs"
    ],
    "note": "A broker reviews every submission, including ones outside the appetite on file."
  }
}

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

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