Overview

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

This is the sandbox environment — it behaves identically to production but uses test data. Use it to build and validate your integration before going live.

Base URL

https://sandbox-api.callplus.be/api/v1

Endpoints

Method	Path	Description
`POST`	`/simulations`	Run a 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": "2024-01-15T10: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": "2024-01-15T10: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`

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.