Overview

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

Two integration surfaces

Call+ provides two ways to integrate, and most partners use both:

The Simulation API — synchronous REST endpoints that your system calls to run simulations and download PDF reports.
Outbound webhooks — signed HTTPS POST requests that Call+ sends to an endpoint you register when real business events occur, starting with plan.launched.

Running a simulation does not emit a webhook. A simulation is a hypothetical calculation; plan.launched is sent only if and when an actual Call+ plan is launched. See the Webhooks overview.

You want to…	Use
Run a simulation and get the figures	`POST /simulations`
Retrieve a previously created simulation	`GET /simulations/{id}`
Download the PDF report	`GET /simulations/{id}/pdf`
React when a Call+ plan is launched	The `plan.launched` webhook — start with the Webhooks overview
Implement and test your webhook endpoint	Building a webhook receiver

Environments

Sandbox and production expose the same endpoints and response envelope, and the sandbox never produces real records.

Temporary schema caveat. The sandbox currently runs an older revision of the request schema: it does not accept sourceReferenceId or companyFiscalData, names the national-register field nationalRegisterNumber (production uses nrn), and caps benefitInKind at €100,000. An aligned sandbox running the exact production schema is planned. Until it ships, use the sandbox to exercise authentication, headers, and the general flow — and validate your final integration against production with a test API key agreed with us.

Environment	Purpose	Base URL	API key prefix
Sandbox	The test base URL — point your client here while you build. Never produces real records; see the schema caveat above.	`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": 50000, "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
`METHOD_NOT_ALLOWED`	405	Use the correct HTTP method for the endpoint
`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 echoes an X-Correlation-Id header, and the body's requestId carries the same value. You may send your own X-Correlation-Id on the request to correlate it with your own logs; if you don't, one is generated for you. Always log this value — it's the fastest way to debug issues with the Call+ team.

The machine-readable contract

The API Reference — including the plan.launched webhook — is generated from a canonical OpenAPI 3.1 document, and every example in these docs validates against it. If you want the file itself — to generate a client, mock the API, or run contract tests — ask us during onboarding and we'll provide the current version.

If you spot a mismatch between this documentation and the API's actual behavior, report it with your requestId — discrepancies are resolved through a tracked change on our side, never something you should have to guess around.