Skip to content
Valjean SpecialtyValjean SpecialtyValjean Developer Docs

Ask to bind a quote

POST
/submissions/{id}/quotes/{quoteId}/bind-request
curl -X POST "https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/quotes/QUOTE_ID/bind-request" \
  -H "Authorization: Bearer $VALJEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Please bind as quoted, effective 12/15/2026","contact_name":"Dana Whitfield","contact_email":"dana@agency.example","accept_subjectivities":true}'

Your written instruction to bind a presented quote. It never binds by itself: your broker confirms with the market and sends the binder, and you get bind.status_changed events.

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.

quoteId
required
string format: uuid

A presented quote’s id.

Query Parameters

Section titled “Query Parameters”
dry_run
string
Allowed values: 1 true

1 to check the request and see what would happen, without saving or sending anything.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
instruction
required
string
>= 10 characters <= 2000 characters
requested_effective_date
string format: date
contact_name
required
string
>= 2 characters <= 120 characters
contact_email
string format: email
/^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/
accept_subjectivities
required
boolean

Example 

{
  "instruction": "Please bind as quoted, effective 12/15/2026",
  "contact_name": "Dana Whitfield",
  "contact_email": "dana@agency.example",
  "accept_subjectivities": true
}

Responses

Section titled “Responses”

200

Section titled “200”

With ?dry_run=1: every check passed and nothing was saved or sent.

Media typeapplication/json

With ?dry_run=1: checked, nothing saved or sent. Other fields describe what would happen (the file’s insured and lines, an existing file’s id, or the quote and its subjectivities).

object
dry_run
required
boolean
valid
required

The request passed every check. A request that fails a check returns the same error it would without dry_run.

boolean
would
required

What sending it for real would do.

string
Allowed values: create return_existing request_bind
note
required
string

Example 

{
  "dry_run": true,
  "valid": true,
  "would": "create"
}

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.

201

Section titled “201”

OK

Media typeapplication/json
object
bind_request_id
required
string format: uuid
status
required
string
Allowed value: preparing
status_text
required
string
quote
required
object
id
required
string format: uuid
carrier
required
string
premium
required
number
subjectivities
required
string | null
note
required
string

Example 

{
  "bind_request_id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "status": "preparing",
  "status_text": "Received: your broker is preparing it",
  "quote": {
    "id": "6f1d2c3b-8a9e-4b7c-9d10-1e2f3a4b5c6d",
    "carrier": "Magnolia Underwriting Managers",
    "premium": 17075
  },
  "subjectivities": "Signed application; currently valued loss runs",
  "note": "Not bound yet. Your broker confirms it with the market and sends the binder; you'll get bind.status_changed events."
}

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