Download a document

GET

/submissions/{id}/documents/{docId}

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

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

A download link good for 5 minutes. Add ?redirect=1 to be redirected to the file instead. The link is a credential: don’t log or share it.

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

Authorizations

• bearerAuth
• apiKeyHeader
• oauth2
  read

Parameters

Path Parameters

id

required

string format: uuid

Submission id.

docId

required

string format: uuid

Document id from the documents list.

Query Parameters

redirect

string

Allowed values: 1

1 to be redirected (302) to the file instead of getting JSON.

Responses

200

OK

Media typeapplication/json

object

file_name

required

string

kind

required

string

url

required

Download link. It’s a credential: don’t log or share it.

string format: uri

expires_in_seconds

required

integer

Example ^generated

{
  "file_name": "example",
  "kind": "example",
  "url": "https://example.com",
  "expires_in_seconds": 1
}

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.

302

With ?redirect=1: redirect to the file.

Headers

Location

string format: uri

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