Skip to main content

​
Prerequisites

  • A SIMCEL account with at least one active Plan
  • An API key (generate one in Settings → API Keys inside the SIMCEL app)

​
Step 1: Get a token

Exchange your API key for a short-lived bearer token. 
curl -X POST https://api.simcel.io/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "sk_live_your_api_key_here"
  }'
Response: 
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}
Tokens expire after 1 hour. Cache the token and refresh it before expiry. Avoid calling /auth/token on every request.

​
Step 2: Find your Plan ID and Scenario IDs

You need a planId and at least one scenarioId for every Insights API call. 
curl https://api.simcel.io/insights/v1/plans \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "plans": [
    {
      "id": "plan_9xKz2",
      "name": "FY2025 Annual Plan",
      "currency": "USD",
      "scenarios": [
        { "id": "scen_abc", "name": "Committed", "flags": ["committed"] },
        { "id": "scen_def", "name": "Optimistic", "flags": [] },
        { "id": "scen_ghi", "name": "Actual", "flags": ["actual"] }
      ]
    }
  ]
}

​
Step 3: Call your first Insights endpoint

Let’s fetch the P&L summary comparing two scenarios: 
curl "https://api.simcel.io/insights/v1/pnl-summary?planId=plan_9xKz2&scenarioIds=scen_abc,scen_def&interval=FY&currency=USD" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response: 
{
  "meta": {
    "planId": "plan_9xKz2",
    "currency": "USD",
    "interval": "FY",
    "generatedAt": "2025-04-14T10:32:00Z"
  },
  "scenarios": [
    {
      "scenarioId": "scen_abc",
      "scenarioName": "Committed",
      "pnl": {
        "grossFIESales": 5200000,
        "netFIESales": 4888000,
        "cogs": 2100000,
        "grossProfit": 2788000,
        "ebit": 2368000,
        "ebitPercent": 0.484,
        "dpm": 1850000,
        "dpmPercent": 0.378
      }
    },
    {
      "scenarioId": "scen_def",
      "scenarioName": "Optimistic",
      "pnl": {
        "grossFIESales": 6100000,
        "netFIESales": 5734000,
        "cogs": 2450000,
        "grossProfit": 3284000,
        "ebit": 2860000,
        "ebitPercent": 0.499,
        "dpm": 2200000,
        "dpmPercent": 0.383
      }
    }
  ]
}
You’re in. Next, explore the full API Reference or jump into the AI Agent guide.