Sandbox Testing

Test your integration without hitting real data sources. The sandbox environment simulates all check workflows.

Getting started

Use a sandbox API key (prefixed gn_test_) to send requests to the same API base URL. Sandbox requests are free and do not appear on your invoice.

curl -X POST https://api.gonos.co/api/v1/candidates \
  -H "X-API-Key: gn_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane", "last_name": "Doe", "email": "jane@example.com"}'

Magic last names

Use these special last names to trigger specific check outcomes. Checks complete instantly in sandbox mode.

Test scenarios

Happy path

1. Create a candidate with last name Testclear
2. Create a consent session and mark it complete
3. Create a check — it completes immediately with disposition clear
4. Fetch the report to verify the results

Adverse action flow

1. Create a candidate with last name Testconsider
2. Complete consent and create a check
3. Initiate an adverse action on the completed check
4. Wait the 5-business-day period (instant in sandbox)
5. Finalize the adverse action

Dispute flow

1. Create a candidate with last name Testdispute
2. Complete consent, create a check, and wait for completion
3. A dispute is auto-filed — test your dispute handling workflow
4. Resolve the dispute to complete the flow

Webhook testing

1. Register a webhook endpoint (use a service like webhook.site for testing)
2. Create checks with different magic last names
3. Verify that your endpoint receives the correct event types
4. Test your signature verification with the webhook secret

Sandbox limitations

• Sandbox checks do not query real data sources (courts, OFAC, NSOPW, etc.)
• Consent sessions auto-complete — no email is sent to the candidate
• Adverse action waiting periods are bypassed
• Sandbox data is periodically purged (every 30 days)
• Rate limits are more lenient in sandbox (300 req/min vs 120 req/min)

Switching to production

When you are ready to go live, swap your API key from gn_test_ to gn_live_. No other code changes are needed — the API surface is identical.