Test Mode & Sandbox

There are two ways to develop your integration safely before going live. Choose based on what you’re building:

Mode	What it does	Use it when
Test mode	Real pipeline runs; submissions marked as previews	You want realistic scores and full reports in your test environment
Sandbox	Stub data returned instantly; nothing stored	You’re building and verifying API calls, field mapping, or error handling

Test keys vs live keys

The environment is set at the key level. There are no separate test and live API URLs — both environments use the same base URL. What differs is the key you authenticate with.

Key prefix	Environment
`inc_test_…`	Test
`inc_live_…`	Live

Create a test key and a live key separately in the portal under API Keys. See API Keys.

Test mode

When you use a test key with the standard live endpoints (e.g. POST /v1/api/applications), the pipeline runs in full — the schema is validated, the AI review runs, scores are generated, and a complete report is produced. The only difference is how the submission is treated afterwards:

It is marked is_preview: true
It is excluded from cohort analytics — won’t affect average scores, pipeline counts, or the cohort overview
It is excluded from the approval pipeline — your team won’t see it in the main submissions list for review
It is visible in the portal under a separate “Preview” filter only
The submission response includes "env": "test" so your system can distinguish test from live responses

This means you can submit hundreds of test applications without polluting your real pipeline or skewing analytics.

Sandbox mode

The sandbox is a set of stub endpoints available exclusively to test keys. They return instant, deterministic responses with no database writes, no queue tasks, and no token usage. Every sandbox endpoint mirrors a live endpoint at the same path under /v1/api/sandbox/.

Use sandbox when you need to:

Verify your HTTP client, headers, and request shape before running the full pipeline
Write and test field-mapping logic without consuming tokens
Build webhook or polling handlers against a predictable response

Authentication — same Bearer token as the live API, but the key must be a test key. Sending a live key to a sandbox endpoint returns 403 with error code sandbox_live_key.

Sandbox endpoints

All sandbox paths are under /v1/api/sandbox/:

Schemas

Register a schema

POST /v1/api/sandbox/schema
Authorization: Bearer inc_test_xxxxxxxxxxxx
Content-Type: application/json

{
  "fields": [
    { "label": "Problem", "key": "problem" },
    { "label": "Solution", "key": "solution" }
  ]
}

Response (201):

{
  "schema_id": "6507f1f77bcf86cd799439aa",
  "fields": [
    { "key": "problem", "label": "Problem", "field_type": "text", "sources": ["clarity"], "clarity_role": "problem", "required": true },
    { "key": "solution", "label": "Solution", "field_type": "text", "sources": ["clarity"], "clarity_role": null, "required": true }
  ],
  "message": "Sandbox: schema registered. Use schema_id in your sandbox submissions. No data was stored."
}

List schemas

GET /v1/api/sandbox/schema
Authorization: Bearer inc_test_xxxxxxxxxxxx

Get a schema

GET /v1/api/sandbox/schema/{schema_id}
Authorization: Bearer inc_test_xxxxxxxxxxxx

Applications

Submit an application

POST /v1/api/sandbox/applications
Authorization: Bearer inc_test_xxxxxxxxxxxx
Content-Type: application/json

{
  "cohort_id": "your-cohort-id",
  "answers": {
    "startup_name": "My Startup",
    "problem": "A description of the problem"
  }
}

Response (202):

{
  "submission_id": "a1b2c3d4e5f6a1b2c3d4e5f6",
  "status": "complete",
  "message": "Sandbox: submission accepted. Insights are available immediately.",
  "env": "test",
  "_sandbox": true
}

Unlike the live endpoint, the sandbox response is immediate — status is already "complete" and insights are available right away without polling.

Get a submission

GET /v1/api/sandbox/applications/{submission_id}
Authorization: Bearer inc_test_xxxxxxxxxxxx

Returns a fixed stub application for a fictional Nigerian fintech, PayFlow NG, with is_preview: true.

Get insights

GET /v1/api/sandbox/applications/{submission_id}/insights
Authorization: Bearer inc_test_xxxxxxxxxxxx

Returns a complete stub report including clarity score, founder fit score, strength criteria, fit dimensions, and a verdict. Use this to build and test any UI or logic that reads back report data.

Programmes

List open cohorts

GET /v1/api/sandbox/programs
Authorization: Bearer inc_test_xxxxxxxxxxxx

Response:

{
  "programs": [
    {
      "id": "6507f1f77bcf86cd799439ab",
      "name": "Sandbox Cohort — Q1 2025",
      "status": "open"
    }
  ]
}

Stub data

All sandbox responses use the same fixed stub applicant: Amara Okafor of PayFlow NG, a mobile-first invoice discounting platform for Nigerian SMEs. The clarity score is 78, founder fit is 81, idea strength is 74, and the verdict is COHORT_PERFECT.

The stub data is rich enough to exercise your full report display or scoring logic. The submission_id you send in a GET or insights request is echoed back — the response is always the same stub regardless of which ID you pass.

Choosing between test mode and sandbox

	Test mode	Sandbox
Pipeline runs	Yes	No
Scores generated	Yes	Stub (fixed values)
Token balance affected	Yes	No
Response time	~15–30 seconds	Instant
Data stored	Yes (preview flag)	No
Best for	End-to-end validation	Building & unit-testing

A practical integration workflow:

Start with sandbox — verify your HTTP client, headers, authentication, and field mapping are correct
Switch to test mode — run the full pipeline with a test key against the real endpoints to confirm scores and reports look right
Go live — swap to your live key

Identifying test vs live in your system

The submission response includes an env field:

{
  "submission_id": "...",
  "status": "pending",
  "env": "test"
}

Store this alongside the submission_id so you can distinguish test records from live ones when polling status or reading insights back.

Switching to live

When you’re ready:

Create a live key in the portal (or use one you created earlier)
Update your configuration to use the inc_live_… key
Point your requests back at the live endpoints (remove /sandbox/ from the path)
Submit one real application and verify it appears in the portal’s main submissions list with is_preview: false

Cleaning up test submissions

Test submissions are hidden from the main review pipeline and don’t affect analytics. You don’t need to delete them — they’re available under the Preview filter if you need to inspect them later. Sandbox submissions are never stored at all.