Overview

The Call+ Simulation API lets you run financial simulations for the Call+ stock option plan and generate PDF reports for beneficiaries.

Environments

Sandbox and production share the same endpoints, request schema, and response envelope — only the base URL and key prefix change. Build against sandbox while you integrate, then swap the base URL and key to go live. No code changes.

Environment	Purpose	Base URL	API key prefix
Sandbox	The test base URL — point your client here while you build. Behaves like production but never produces real records.	`https://sandbox-api.callplus.be/api/v1`	`sk_sbx_…`
Production	Real beneficiary simulations and reports.	`https://api.callplus.be/api/v1`	`sk_prod_…`

_meta.environment in every response is "sandbox" or "production" depending on which base URL you called — use it as a runtime sanity check.

Endpoints

Method	Path	Description
`POST`	`/simulations`	Run a simulation
`GET`	`/simulations/{id}`	Retrieve a previously created simulation
`GET`	`/simulations/{id}/pdf`	Download the PDF report

Response format

Every response follows the same envelope structure:

{
  "success": true,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": { ... },
  "_meta": {
    "timestamp": "2026-02-10T10:30:00.123Z",
    "environment": "sandbox"
  }
}

Field	Type	Description
`success`	boolean	`true` on success, `false` on error
`requestId`	string	Unique ID for tracing — include this when contacting support
`data`	object	Response payload (only on success)
`error`	object	Error details (only on failure)
`_meta`	object	Timestamp and environment identifier

Error format

When success is false, the error object contains:

{
  "success": false,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters.",
    "details": [
      {
        "field": "benefitInKind",
        "code": "VALUE_TOO_LARGE",
        "message": "Value exceeds maximum allowed",
        "received": 150000,
        "constraint": { "max": 100000, "inclusive": true }
      }
    ]
  },
  "_meta": {
    "timestamp": "2026-02-10T10:30:00.123Z",
    "environment": "sandbox"
  }
}

Error codes

Code	HTTP	What to do
`VALIDATION_ERROR`	400	Check the `details` array for specific field issues
`INVALID_REQUEST`	400	Fix malformed JSON, unknown fields, or type mismatches
`UNAUTHORIZED`	401	Verify the `X-API-Key` header is present and correct
`FORBIDDEN`	403	Contact support — account may be suspended
`NOT_FOUND`	404	Verify the simulation ID
`RATE_LIMIT_EXCEEDED`	429	Wait for `Retry-After` seconds and retry
`INTERNAL_ERROR`	500	Retry later or contact support with `requestId`

The same codes apply in both environments.

Request ID

Every response includes an X-Request-Id header and a requestId in the body. Always log this value — it's the fastest way to debug issues with the Call+ team.