One policy, with invoices and documents

GET

/policies/{id}

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

• Live and demo (the key decides which book you see)

The policy, the invoices Valjean has sent for it, and its binder, policy and endorsement documents.

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

Authorizations

• bearerAuth
• apiKeyHeader
• oauth2
  read

Parameters

Path Parameters

id

required

string format: uuid

Policy id.

Responses

200

OK

Media typeapplication/json

object

id

required

string format: uuid

submission_id

required

string format: uuid

insured

required

string

policy_number

required

string | null

carrier

required

string

lines

required

Array<string>

effective_date

required

string format: date

expiration_date

required

string format: date

status

required

string

Allowed values: bound issued cancelled expired renewed

premium

required

number

fees

required

number

taxes

required

Surplus lines tax and stamping fee.

number

total

required

number

agent_commission

required

Your agency’s commission on the policy, in dollars.

number | null

policy_document

required

True when the policy document is on file.

boolean

invoices

required

Array<object>

object

id

required

string format: uuid

invoice_number

required

integer

issued_on

required

string | null format: date

due_on

required

string | null format: date

amount_due

required

number

status

required

string

Allowed values: sent paid overdue

paid_on

required

string | null format: date

documents

required

Array<object>

object

id

required

string format: uuid

source

required

“file”: the submission’s documents. “carrier”: presented quotes, binders, policies, endorsements.

string

Allowed values: file carrier

kind

required

Document type, or the carrier document kind (quote, binder, policy, endorsement).

string

file_name

required

string

size_bytes

required

integer | null

created_at

required

string format: date-time

Example

{
  "status": "bound",
  "invoices": [
    {
      "status": "sent"
    }
  ],
  "documents": [
    {
      "source": "file"
    }
  ]
}

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.

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

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

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

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

Retry-After

integer

Example

60

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.

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