Skip to main content
The kycert sandbox is a full-featured test environment. Bureau runs triggered with sandbox API keys (sk_test_...) use fixture data instead of querying live data sources, so you can build and validate your integration without consuming credits, touching real customer data, or producing compliance artifacts. Webhook events fire exactly as they do in production, making end-to-end integration testing straightforward.

​
Getting a sandbox key

Follow the same steps as creating a live key (see Authentication), but select Sandbox for the environment in step 4. Your sandbox key will begin with sk_test_. Use this key in all development and staging environments — never use a sk_live_ key outside production. 
# Sandbox request — identical to production except for the key prefix
curl -X POST https://admin.kycert.com.br/api/v1/bureau/runs \
  -H "X-API-Key: sk_test_your_sandbox_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "subject": {
      "type": "pf",
      "doc": "00000000191"
    },
    "external_id": "test_cust_001"
  }'
Your template_id must be a real template that exists in your tenant’s dashboard. Create a template in the kycert dashboard before running sandbox tests. The same template IDs work in both production and sandbox.

​
Test CPFs

Each test CPF produces a deterministic result every time. Use them to exercise each decision branch in your integration.
CPFDecisionRisk BandScenario
000.000.001-91APPROVEDLOWClean profile — no flags across any source
000.000.002-81BLOCKEDCRITICALCancelled CPF — blocked at critical stage
000.000.003-72BLOCKEDCRITICALActive arrest warrant
000.000.004-53PENDING_REVIEWHIGHActive PEP (politically exposed person)
000.000.005-44BLOCKEDCRITICALOFAC sanctions list
000.000.006-34PENDING_REVIEWHIGHFinancial protests on record
000.000.007-25PENDING_REVIEWHIGHAdministrative improbity finding
000.000.008-06PARTIALMEDIUMThree data sources timed out — partial result
000.000.009-87BLOCKEDCRITICALAll negative flags active simultaneously

​
Test CNPJs

Use these to test PJ (legal entity) bureau runs in your integration.
CNPJDecisionRisk BandScenario
00.000.000/0001-91APPROVEDLOWClean company — no flags
00.000.000/0002-76BLOCKEDCRITICALOFAC financial crime sanction
00.000.000/0003-57PENDING_REVIEWHIGHPEP exposure via company shareholders
00.000.000/0004-81BLOCKEDCRITICALCVM (securities regulator) enforcement action

​
How sandbox differs from production

The sandbox API behaves identically to production with these specific differences:
  • Fixture data, not real bureau queries — responses are pre-programmed for each test document. No external data sources are contacted.
  • No credits consumed — sandbox runs are free and do not deduct from your bureau credit balance.
  • Deterministic results — the same test document always produces the same decision, risk_band, and check results. Your test suite can rely on this.
  • Webhook events fire normally — run.completed and run.failed events are delivered to your webhook endpoint just as in production. The livemode field in the payload is false for sandbox events.
  • Same error behavior — validation errors, rate limits, and authentication failures behave the same as in production.

​
Suggested test scenarios

Cover these scenarios before deploying to production:
  1. Happy path — use 000.000.001-91 (CPF) or 00.000.000/0001-91 (CNPJ) to verify your system correctly handles an APPROVED decision and proceeds with onboarding.
  2. Hard block — use 000.000.005-44 to verify your system blocks the customer and does not allow the operation to proceed.
  3. Manual review queue — use 000.000.004-53 to verify your system correctly holds the customer pending a compliance decision.
  4. Partial result — use 000.000.008-06 to verify your system handles a PARTIAL decision without crashing, and routes the case to your compliance team.
  5. Retry on run.failed — simulate a failed run by triggering an error condition and verify your retry logic is working.
  6. Webhook signature verification — confirm your HMAC-SHA256 verification rejects a request with a tampered payload. See Webhooks for verification code.
Use sandbox keys throughout development and integration testing. Switch to live keys only when deploying to production. If you accidentally trigger a production run during testing, contact support — do not attempt to reverse the bureau result manually.