Upload a document (up to 4 MB)

POST

/submissions/{id}/documents

curl -X POST "https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/documents" \
  -H "Authorization: Bearer $VALJEAN_KEY" \
  -F "file=@loss-runs.pdf;type=application/pdf"

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([await fs.promises.readFile("loss-runs.pdf")], { type: "application/pdf" }), "loss-runs.pdf");
const res = await fetch("https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/documents", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VALJEAN_KEY}` },
  body: form,
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/documents",
    headers={"Authorization": f"Bearer {os.environ['VALJEAN_KEY']}"},
    files={"file": ("loss-runs.pdf", open("loss-runs.pdf", "rb"), "application/pdf")},
)
print(res.json())

Multipart/form-data with “file” and an optional “doc_type”. Valjean reads it with AI and updates what’s needed. Over 4 MB: use an upload link.

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

Authorizations

bearerAuth
apiKeyHeader
oauth2
submit

Parameters

Path Parameters

required

string format: uuid

Submission id.

Request Body^required

multipart/form-data

object

file

required

string

doc_type

string

/^[a-z0-9_]{2,40}$/

Responses

201

application/json

object

document_id

required

string format: uuid

file_name

required

string

doc_type

required

Detected or given document type, e.g. acord_125, loss_runs, sov, other.

string

note

string

duplicate

Only on /documents/complete when the upload was already recorded.

boolean

Example

{
  "document_id": "53a6ee6c-2017-4da0-83ab-e9703f6ff67e",
  "file_name": "Loss runs 2021-2026.pdf",
  "doc_type": "loss_runs",
  "note": "Received. Valjean reads it and updates what's still needed in a minute or two."
}

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

Fix the request and send it again (invalid_request, invalid_json).

application/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

Key or token missing, wrong, expired or revoked (unauthorized). Don’t retry: get a new key or sign in again.

application/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.

application/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.

application/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

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.

application/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

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

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

415

File type not accepted (unsupported_type): PDF, images, Word, Excel, CSV or text.

application/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": "unsupported_type",
    "message": "Send PDF, image, Word, Excel, CSV or text files."
  }
}

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.

application/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

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.

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

Upload a document (up to 4 MB)

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

201

Example

Headers

Example

400

Example

401

Example

403

Example

404

Example

409

Example

413

Example

415

Example

429

Example

Headers

Example

500

Example

Request Body^required