Skip to content
BrazID

Sandbox

Test your integration without spending credits and without depending on real data.

Download Insomnia

A collection with every request in this guide. In Insomnia, import the file and fill in api_key in the environment.

  • The address is https://api-sandbox.brazid.com. Paths, parameters and responses are the same as in production.
  • Use a sandbox key: in the dashboard, under API keys, pick the Sandbox environment when you create the key. It starts with brz_test_. A sandbox key does not work in production, and a production key does not work in the sandbox (401 with the code WRONG_ENVIRONMENT).
  • No lookup uses a credit. credits_remaining shows your account’s real balance, which does not change.
  • Only the test CPFs in the table below have data. Any other valid CPF answers 404, and the date of birth must be the one in the table.
  • Each lookup takes about 400 ms, so you can see how your code behaves with a real API. One of the CPFs takes 3 seconds, to test timeouts.
  • The same requests-per-second limits of your plan apply. Batches and the batch.completed webhook also work.
  • Every response carries the x-brazid-env: sandbox header.

cURL

1curl -X POST https://api-sandbox.brazid.com/v1/cpf \2 -H "x-api-key: $BRAZID_API_KEY" \3 -H "Content-Type: application/json" \4 -d '{"cpf":"529.982.247-25","birthdate":"1982-11-26"}'

200 OK

1{2 "success": true,3 "data": {4 "cpf": "52998224725",5 "name": "MARIA SOUZA LIMA",6 "birthdate": "26/11/1982",7 "day": 26,8 "month": 11,9 "year": 1982,10 "situation": "REGULAR",11 "social_name": null,12 "registration_date": "12/03/2004"13 },14 "credits_remaining": 1915}

Test CPFs

CPFDate of birthWhat happens
Successful lookups
529.982.247-251982-11-26Regular holder, fast response.
111.444.777-351990-05-02Regular holder, fast response.
300.000.001-161993-09-17Regular holder.
300.000.003-881958-07-08Long name with accents and an apostrophe (D'ÁVILA).
300.000.004-692012-10-03Holder under 18.
Registration status
100.000.001-081988-01-15Registration status SUSPENSA.
100.000.002-801995-12-09Registration status PENDENTE DE REGULARIZAÇÃO.
100.000.003-611969-06-21Registration status CANCELADA DE OFÍCIO.
300.000.002-051984-02-29Registration status NULA.
Incomplete or unusual data
390.533.447-051976-08-30Optional field null: situation comes back null.
Slow responses
200.000.001-081991-04-04Slow response, 3 seconds.
400.000.001-241987-12-01Very slow response, 9 seconds, to trigger timeouts.
Errors
000.000.001-911980-01-01Valid CPF with no record: 404.
999.999.990-501980-01-01Simulated provider failure: 503 (in a batch, the item comes back with status error).

Names and dates are fictional. If the date you send is not the one in the table, the answer is 404, as in production.

Test scenarios

  • Normal flow

    Look up 300.000.001-16 with the date from the table and confirm your integration reads name, birthdate and situation.

  • Holder not found (404)

    Look up 000.000.001-91, any valid CPF outside the table, or a CPF from the table with a different date of birth. A 404 is a normal result: your system should not treat it as a failure.

  • Provider unavailable (503)

    The CPF 999.999.990-50 always answers 503. Use it to test retries with growing waits and the message shown to the user. In a batch, the item comes back with status error.

  • Slow response and timeout

    The CPF 200.000.001-08 takes 3 seconds and 400.000.001-24 takes 9. With your HTTP client timeout set to 5 seconds, the first should pass and the second should time out.

  • Registration status

    The CPFs 100.000.001-08, 100.000.002-80, 100.000.003-61 and 300.000.002-05 come back with a status other than REGULAR. Test whether your system blocks or flags these holders.

  • Null fields

    The CPF 390.533.447-05 returns situation as null. Make sure your code does not break on null.

  • Accents and minors

    The CPF 300.000.003-88 has a long name with accents and an apostrophe, and 300.000.004-69 belongs to a minor. Check your UTF-8 handling and age rules.

  • Malformed CPF (400 and 422)

    No table needed: 1234567890 (10 digits) answers 400 and 529.982.247-26 (wrong check digit) answers 422. The same validations as production apply.

  • Wrong-environment key (401)

    Call the sandbox with a production key (or production with a sandbox key) to see the 401 with the code WRONG_ENVIRONMENT.

  • Rate limit (429)

    Your plan’s per-second limit also applies in the sandbox. Send more parallel requests than the limit to see the 429 and the Retry-After header.

Mixed batch

This batch brings together six situations: three CPFs found, one not found, one with a provider failure and one with an invalid check digit. In the summary, expect found 3, not_found 1, invalid 1 and errors 1.

cURL

1curl -X POST https://api-sandbox.brazid.com/v1/cpf/batch \2 -H "x-api-key: $BRAZID_API_KEY" \3 -H "Content-Type: application/json" \4 -d '[{"cpf":"529.982.247-25","birthdate":"1982-11-26"},{"cpf":"300.000.001-16","birthdate":"1993-09-17"},{"cpf":"300.000.003-88","birthdate":"1958-07-08"},{"cpf":"000.000.001-91","birthdate":"1980-01-01"},{"cpf":"999.999.990-50","birthdate":"1980-01-01"},{"cpf":"529.982.247-26","birthdate":"1982-11-26"}]'

summary

1{2 "summary": {3 "found": 3,4 "not_found": 1,5 "invalid": 1,6 "errors": 1,7 "insufficient_credits": 08 }9}