Skip to content

Quick Start

Quick Start

Section titled “Quick Start”

Get up and running with the Illustrata API in just a few minutes.

Before You Begin

Section titled “Before You Begin”

You’ll need the following from your administrator:

  • Product slug — e.g., my-annuity
  • API key — your unique authentication credential
  • Input fields — the specific fields your product requires

The base URL is https://staging-api.illustrata.io. Replace YOUR_PRODUCT_SLUG and YOUR_API_KEY in the examples below with the values from your administrator.

Step 1: Make a JSON Request

Section titled “Step 1: Make a JSON Request”

Retrieve calculated outputs as JSON. Your administrator will provide the exact field names and values required for your product.

Terminal window
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": {
      "Owner_FirstName": "Valued",
      "Owner_LastName": "Owner",
      "Owner_DOB": "1980-01-01",
      "Owner_Gender": 1,
      "Owner_Type": -2,
      "Annuitant_FirstName": "Valued",
      "Annuitant_LastName": "Annuitant",
      "Annuitant_DOB": "1946-01-01",
      "Annuitant_Gender": 1,
      "Annuitant_Type": -3,
      "State": 7,
      "Premium": 100000,
      "TaxQualification": 2,
      "PaymentMode": 1,
      "PaymentOption": 1,
      "WDType": 5,
      "WDAmount": 1000,
      "WDMode": 1,
      "WDStartDuration": 1,
      "Rider1": 1,
      "Rider2": 1
    }
  }'

Response:

{
  "status": 200,
  "response_data": {
    "outputs": {
      "result_field": 42500,
      "another_output": "value"
    }
  }
}

Step 2: Download a PDF

Section titled “Step 2: Download a PDF”

Add ?format=pdf to receive a PDF file:

Terminal window
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": {
      "Owner_FirstName": "Valued",
      "Owner_LastName": "Owner",
      "Owner_DOB": "1980-01-01",
      "Premium": 100000,
      "State": 7
    }
  }'

The response will be a PDF file saved as illustration.pdf.

Step 3: Get JSON + PDF Together

Section titled “Step 3: Get JSON + PDF Together”

Use ?format=both to receive outputs and the PDF in one call:

Terminal window
curl -X POST "https://staging-api.illustrata.io/api/YOUR_PRODUCT_SLUG?format=both" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "Owner_FirstName": "Valued",
      "Owner_LastName": "Owner",
      "Owner_DOB": "1980-01-01",
      "Premium": 100000,
      "State": 7
    }
  }'

Response includes both outputs and a base64-encoded PDF:

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

Common Issues

Section titled “Common Issues”

401 — API key not working

  • Confirm the key was copied correctly from your administrator
  • Verify the Authorization: Bearer prefix is included

403 — Access denied to product

  • Confirm the product slug with your administrator
  • Your key may not be authorized for this product

400 — Validation error

  • Check that all required input fields are present
  • Verify field names match exactly what your administrator provided (case-sensitive)

Next Steps

Section titled “Next Steps”