Skip to content

Your First API Call

This walkthrough takes you from zero to a completed engine execution. We'll use curl — adapt the commands to your language of choice (see Code Examples).

Prerequisites

You need these from your tenant administrator:

  • API key: e.g. acme-insurance_550e8400-e29b-41d4-a716-446655440000
  • Tenant slug: e.g. acme-insurance
  • Engine slug: e.g. property-calculator

Step 1: Discover the Engine

First, check what inputs the engine expects:

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://api.xlsxapi.eu/jobs/about/acme-insurance/property-calculator \
  | python3 -m json.tool

{
  "name": "Property Calculator",
  "slug": "property-calculator",
  "description": "Calculate property insurance premiums",
  "version": "2.1",
  "input_schema": {
    "type": "object",
    "properties": {
      "customerAge": { "type": "integer", "minimum": 18, "maximum": 100 },
      "propertyValue": { "type": "number", "minimum": 0 }
    },
    "required": ["customerAge", "propertyValue"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "premium": { "type": "number" },
      "deductible": { "type": "number" }
    }
  },
  "updated_at": "2026-03-10T14:30:00Z"
}

The input_schema tells you exactly what fields to send and their constraints. The output_schema tells you what to expect back.

Step 2: Execute the Engine

Submit your inputs. The API returns immediately with a job ID — processing happens asynchronously.

curl -s -X POST \
  https://api.xlsxapi.eu/jobs/execute/acme-insurance/property-calculator \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "customerAge": 35,
      "propertyValue": 500000
    }
  }' | python3 -m json.tool

{
  "job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "pending",
  "message": "Job queued for processing",
  "created_at": "2026-03-18T10:30:00Z"
}

Response code: 202 Accepted

The 202 status means the job has been queued, not that it's finished. Save the job_id to check results.

Step 3: Poll for Results

Check the job status. Most jobs complete in 2–5 seconds.

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://api.xlsxapi.eu/jobs/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  | python3 -m json.tool

While processing:

{
  "job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "processing",
  "created_at": "2026-03-18T10:30:00Z",
  "updated_at": "2026-03-18T10:30:05Z"
}

When complete:

{
  "job_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "completed",
  "inputs": {
    "customerAge": 35,
    "propertyValue": 500000
  },
  "outputs": {
    "premium": 1250.50,
    "deductible": 1000,
    "coverage": 500000
  },
  "created_at": "2026-03-18T10:30:00Z",
  "completed_at": "2026-03-18T10:30:08Z",
  "execution_time_ms": 1850
}

Your results are in outputs.

Step 4 (Optional): Download the Excel File

If your consumer has download permission, you can get the filled Excel file:

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://api.xlsxapi.eu/jobs/7c9e6679-7425-40de-944b-e07fc1f90ae7/download \
  | python3 -m json.tool

{
  "download_url": "https://...",
  "filename": "property-calculator_7c9e6679_20260318_103000.xlsx",
  "expires_at": "2026-03-18T11:30:00Z"
}

The download_url is pre-authenticated — download it directly without any headers. It expires in approximately 1 hour.

Using Webhooks Instead of Polling

Instead of polling, you can provide a webhook_url when executing:

curl -s -X POST \
  https://api.xlsxapi.eu/jobs/execute/acme-insurance/property-calculator \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "customerAge": 35, "propertyValue": 500000 },
    "webhook_url": "https://your-app.com/webhooks/xlsxapi"
  }'

The platform will POST the results to your URL when the job finishes. See Webhooks for payload details.

Next Steps