Frequently Asked Questions

What does the CPFHub.io API return?

Simple Lookup (GET /cpf/{cpf}) and batch lookup (POST /cpf/bulk): full name, gender and date of birth from the CPF (Brazil's individual taxpayer ID). Real-Time Lookup (POST /cpf/realtime): name, date of birth, year of death (deathYear, an integer or null), registration status at Receita Federal (Brazil's federal tax authority), control code and proof. It does not return a score, an email, or the day or month of death.

Does CPFHub.io query Receita Federal live?

It depends on the route. GET /cpf/{cpf} answers from our database with a typical time of ~150 ms (not an SLA), returning name, gender and date of birth (1 credit per CPF found). POST /cpf/realtime queries Receita Federal at the moment of the call and returns registration status, year of death (deathYear, an integer or null), control code and proof, but it requires the holder's date of birth and takes about 1 second (typical time, not an SLA). It uses 1.5 credits only on an HTTP 200 response. Failures, including a mismatched date of birth (HTTP 422), do not use credits. The routes are independent, so one never falls back to the other.

Can I validate a CPF and a name at signup?

Yes. You send the CPF, receive the name and date of birth, and compare them with what the user typed in your flow (fraud prevention or signup). The matching rule lives in your system.

Is there a batch lookup?

Yes. POST /cpf/bulk is asynchronous and accepts up to 10,000 CPFs per request. Only CPFs found use credits. It is useful for cleaning up a database. Without code, use the batch lookup in the dashboard (app.cpfhub.io/lote) with a CSV or TXT file.

Does CPFHub.io do KYC (know your customer) with a selfie or OCR?

No. The product is CPF lookup: simple (GET), batch and real-time at Receita Federal (POST). No biometrics, selfie or document OCR.

What is the SLA (uptime guarantee)?

By plan, on the pricing page (/pricing): Free 95%, Pro 99%, Enterprise 99.9%. The typical time of the Simple Lookup is ~150 ms and that of the Real-Time Lookup is about 1 second. These are typical references, not an SLA. For the batch lookup, time depends on how many CPFs are in the submission, and each lookup stays in the same range as the Simple Lookup.

Does the Real-Time Lookup return the year of death?

Yes. POST /cpf/realtime returns deathYear, the year of death, always present as an integer or null. It does not return the day or month. null appears when no death is recorded or when the value received is invalid (it does not have 4 digits, falls outside the range between 1900 and the current year, or is earlier than the birth year).

How do I get my API key?

When you create your account, an API key is generated automatically. Go to app.cpfhub.io/api-keys to view and copy it at any time. If needed, you can generate a new key on that same page.

Does the Free plan have a lookup limit?

Yes. The Free plan includes 50 credits per month and the API stops responding when they run out. Paid plans offer larger volumes. See the available plans on the pricing page.

Is there a sandbox for testing?

Testing happens directly on the production API: every account includes 50 free credits per month. Use them to test your integration in production at no cost. A CPF that is not found (404) and CPFs with an incorrect format or check digit (400/422) never use credits, so you can test error scenarios freely.

What happens when the CPF is not found?

The API returns HTTP 404 with error.message "CPF não encontrado na base de dados" (Portuguese for "CPF not found in the database"). That lookup does not deduct credits from your plan, so you only pay for successful lookups.

Do CPFs with an incorrect format or check digit also use credits?

No. A CPF with an incorrect format (HTTP 400) or wrong check digits (HTTP 422) does not use credits. The reason comes in error.message. Only lookups where the CPF is found are charged: HTTP 200 on the Simple Lookup and the Real-Time Lookup, or found: true on each batch item.

Does the API store the CPFs I look up?

Yes. Each lookup is recorded with the CPF queried, the result, the date and the account that made the lookup, including when the CPF is not found. The record serves the dashboard history, credit billing, auditing and fraud prevention. In the Real-Time Lookup, the HTML proof is also stored. Retention details are on the compliance page.

Is the API compatible with LGPD (Brazil's data protection law)?

Yes. The API queries only data from public sources and returns no sensitive information beyond name, gender and date of birth (and, in the Real-Time Lookup, the registration status and year of death at Receita Federal). Use is allowed for legitimate purposes, such as identity verification, signup validation and fraud prevention.

What is the average response time?

The typical time of the Simple Lookup is ~150 ms and that of the Real-Time Lookup is about 1 second. These are typical references, not an SLA. For the batch lookup, time depends on how many CPFs are in the submission, and each lookup stays in the same range as the Simple Lookup. The availability SLA varies by plan: Free 95%, Pro 99%, Enterprise 99.9%. See /pricing and the status at app.cpfhub.io/status.

Can I use the API in the frontend (browser)?

Technically yes, but it is not recommended. Exposing your API key in client-side code is a security risk. Always make calls from a backend (server, serverless function, Next.js API Route) and never include the key in public code.

Is there a limit on requests per second or per minute?

Yes, per minute and per API key: by default, 30 requests per minute on the Simple Lookup (each batch submission counts as 1) and 5 per minute on the Real-Time Lookup. Custom plans may have different limits, so confirm with CPFHub.io support at suporte@cpfhub.io. Above the limit, the API responds HTTP 429 with the Retry-After header (seconds to wait), without using credits. Also, when credits run out on a plan without overage billing, the API responds HTTP 403 with the message "Limite de créditos excedido" ("credit limit exceeded").

Is there an SDK for my language?

The API is REST: a GET with the x-api-key header, which works in any language with an HTTP client. The SDKs and examples page has ready examples for 18 languages and frameworks, such as Node.js, Next.js, Python, PHP, Laravel, Ruby, Go, Java, .NET and curl. The official published SDK is the Python one (pip install cpfhub). For the other languages, use the HTTP client.

How do I cancel my subscription?

Go to the dashboard at app.cpfhub.io, open Settings → Subscription and click Cancel plan. The cancellation request is processed immediately, and you keep access to the plan until the end of the period you already paid for.

Does CPFHub.io offer technical support?

Yes. Customers on paid plans get email support with a response SLA of up to 24 business hours. For quick questions, the documentation and the playground cover most cases.