Test mode

Develop and test your Flow9 integration without any real-world side effects. Test mode is entered by using a test API key — nothing about the request body…

Develop and test your Flow9 integration without any real-world side effects. Test mode is entered by using a test API key — nothing about the request body or headers turns it on, so it can never be toggled by accident or by untrusted input.

Getting a test key

In Settings → Developers → API keys, create a key and choose the Test environment. Test keys are prefixed f9_test_ (legacy wcrm_test_ keys work too). Live keys are prefixed f9_live_.

# A test key looks like this — note the f9_test_ prefix:
export F9_TEST_KEY="f9_test_0123456789abcdef0123456789abcdef"

Use it exactly like a live key:

curl https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/health \
  -H "x-api-key: $F9_TEST_KEY"

What test mode guarantees

Guarantee	Behaviour
No real sends, ever	Enrolling a record into a workforce that would send SMS/email, place a call, send a fax, or run a voice worker performs nothing. The API returns a simulated outcome instead.
No wallet spend	Because no send happens, your messaging/wallet balance is never charged in test mode.
Clearly labelled	Responses produced by a test key carry "test_mode": true so your integration can assert it is talking to the sandbox.
Server-side, not cosmetic	The decision is made in the service layer from the authenticated key’s environment — it cannot be spoofed by a header or body field.

Example: enrolling in a sending workforce

curl -X POST https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/workforces/$WF_ID/enroll \
  -H "x-api-key: $F9_TEST_KEY" -H "content-type: application/json" \
  -d '{"subject_type":"lead","subject_id":"'$LEAD_ID'"}'

Response (nothing was sent):

{
  "enrolled": false,
  "reason": "simulated: test mode performs no real enrollment or sends",
  "test_mode": true,
  "simulated": true,
  "kind": "workforce_run",
  "message": "Simulated in test mode — no real workforce run was performed.",
  "detail": { "workflow_id": "…", "subject_type": "lead" }
}

The same call with a live key (f9_live_…) enrolls the record for real.

A fully separate sandbox

• Isolated dataset — records created with a test key carry test_mode = true and are scoped away from live keys at the query layer (hard server-side scoping, not UI filtering): a test key reads and writes only test records, a live key only live ones. Children (notes, tasks, activities) inherit isolation through their parent.

• POST /v1/test-mode/reset — wipe your test dataset on demand:

  curl -X POST https://mwxpyoqrtdfxubdotbmj.supabase.co/functions/v1/public-api/v1/test-mode/reset \
    -H "x-api-key: $F9_TEST_KEY"
  

  Deletes every record your test keys created (and their children); live data is never touched. Only a test-mode key may call it — a live key gets 403.

Create a test key from Developers → API keys → Create, with the environment set to Test (the key starts f9_test_).

See authentication for key management and errors for the error envelope.