Product Endpoint

POST /api/{productSlug}

Submit input data for an insurance illustration product. Returns calculated outputs as JSON, a PDF document, or both.

Authentication

Required. Pass your API key via Authorization: Bearer or X-API-Key header. See Authentication for details.

Path Parameters

Parameter	Type	Description
productSlug	string	Your product identifier, provided by your administrator

Query Parameters

Parameter	Type	Values	Description
format	string	json, pdf, both	Override the default response format for this request

If format is omitted, the product’s default format is used (configured by your administrator).

Request Body

{
  "inputs": {
    "FieldName": "value",
    "AnotherField": 100000
  }
}

The fields inside inputs are specific to your product. Your administrator will provide the list of required and optional fields.

Responses

JSON — 200 OK

Returned when ?format=json or the product default is JSON.

{
  "status": 200,
  "response_data": {
    "outputs": {
      "OutputField1": 42500.00,
      "OutputField2": "some value",
      "OutputField3": true
    }
  }
}

The fields inside outputs vary by product. Your administrator can provide the full list of output fields.

PDF — 200 OK

Returned when ?format=pdf.

Content-Type: application/pdf
Content-Disposition: attachment; filename="illustration_2025-01-15T10-30-00.pdf"

The response body is the raw PDF binary. Save it directly to a file.

Both — 200 OK

Returned when ?format=both. JSON outputs plus a base64-encoded PDF in a single response.

{
  "status": 200,
  "response_data": {
    "outputs": {
      "OutputField1": 42500.00
    }
  },
  "pdf": {
    "fileName": "illustration_2025-01-15T10-30-00.pdf",
    "data": "JVBERi0xLjQK...",
    "pageCount": 12
  }
}

To convert the base64 PDF to a file:

const pdfBytes = Buffer.from(response.pdf.data, 'base64')
fs.writeFileSync(response.pdf.fileName, pdfBytes)

Error Responses

Status	Description
400	Missing or invalid input data
401	Invalid, missing, or expired API key
403	API key not authorized for this product
404	Product not found or inactive
429	Rate limit exceeded — check Retry-After header
500	Internal server error
502	Upstream service authentication failed — contact your administrator
503	Upstream service unavailable — retry with backoff

Error response body:

{
  "error": "Human-readable description of the error"
}

Examples

cURL — JSON request

curl -X POST "https://staging-api.illustrata.io/api/YOUR_PRODUCT_SLUG" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "field1": "value1",
      "field2": 100000
    }
  }'

cURL — PDF download

curl -X POST "https://staging-api.illustrata.io/api/YOUR_PRODUCT_SLUG?format=pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o illustration.pdf \
  -d '{
    "inputs": {
      "field1": "value1",
      "field2": 100000
    }
  }'

Node.js — JSON request

const response = await fetch(`${BASE_URL}/api/${PRODUCT_SLUG}`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    inputs: {
      field1: 'value1',
      field2: 100000,
    },
  }),
})

const data = await response.json()
console.log(data.response_data.outputs)

Node.js — PDF download

const response = await fetch(`${BASE_URL}/api/${PRODUCT_SLUG}?format=pdf`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    inputs: { field1: 'value1', field2: 100000 },
  }),
})

const buffer = await response.arrayBuffer()
fs.writeFileSync('illustration.pdf', Buffer.from(buffer))