The pain of validating CURPs one by one
If your business deals with long lists of CURPs — payrolls, customer databases, patient files, school records — you already know the pattern: make a call, wait for the response, make the next one, wait, and repeat for hundreds or thousands of records.
Doing it by hand is impossible. Doing it in code is not trivial either: you have to orchestrate the calls, throttle concurrency so you don't overwhelm your own system, handle retries when something fails, track which ones already responded and which ones are still pending, and resume the work if your process crashes halfway through.
What looked like a simple task becomes a mini queueing system that your team has to build, test and maintain. Meanwhile, the database of employees or customers stays unvalidated.
One request, the whole list
That is why we now offer a new batch processing endpoint for CURP validation. The idea is straightforward: instead of making one call per CURP, you send the full list in a single request and receive a batch identifier. From there you can check the status whenever you want and, when everything is done, pull the results.
Your code gets dramatically simpler. There is no orchestration to write: our service takes care of processing every CURP, handles internal retries when a record takes a moment to respond, and keeps a progress log you can query at any time.
How to use it
The flow is direct. You send a single request with your list of CURPs (or personal-data lookups, depending on the mode you pick) and you get a batch ID back.
1. You submit the batch
Each item in the list is a CURP you want to validate. If you want, you can attach a custom label — useful for tying the result back to a record in your own system, like an internal employee ID:
curl -X POST "https://api.tlaloc.sh/mx/v1/curp/batch" \
-H "Authorization: Bearer tlmx_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "curp",
"items": [
{"curp": "MAVR830713HDFRJC07", "ref": "emp-001"},
{"curp": "GOLA901225MDFNRS02", "ref": "emp-002"},
...
]
}'The response confirms the batch was accepted and gives you the identifier:
{
"id": 12345,
"status": "queued",
"items_total": 200,
"_links": {
"self": "/v1/curp/batch/12345",
"items": "/v1/curp/batch/12345/items"
}
}2. You check the status whenever you want
While your batch is being processed, you can poll the progress. You will see how many CURPs are already done, how many are still pending, and the running cost of the operation:
curl "https://api.tlaloc.sh/mx/v1/curp/batch/12345" \
-H "Authorization: Bearer tlmx_YOUR_API_KEY"The status field tells you whether the batch is queued, processing or finished. When it finishes, you know it is time to fetch the results.
3. You get the full results back
Once the batch ends, you download the results in one shot. Each item includes the CURP you submitted (with its optional label), the lookup status, and the official record data:
curl "https://api.tlaloc.sh/mx/v1/curp/batch/12345/items" \
-H "Authorization: Bearer tlmx_YOUR_API_KEY"Two modes: by CURP or by personal data
The endpoint accepts two types of input, depending on what you have:
- Type
curp: you send the CURPs and receive the complete official record (full names, last names, date of birth, state, birth certificate data). - Type
search: you send personal data (first names, last names, date of birth, gender, state of birth) and receive the matching CURP. Handy when you don't have the CURP on file or when you want to confirm the personal data matches an official record.
Each batch is a single type, which keeps the request clear and predictable.
Advantages over the one-by-one approach
Beyond the convenience, batch processing offers concrete benefits:
- Significantly faster for high volume. Validating a list in batch mode is far quicker than firing the queries one by one, because our service parallelizes the work internally.
- No orchestration on your side. You don't have to write queue code, retry logic, concurrency throttling or partial-failure handling. All of that lives in our infrastructure.
- Automatic resilience. If something hiccups along the way — a restart, a network blip, a record that takes longer than usual — the batch picks up where it left off and finishes. You don't lose your progress.
- Built-in deduplication. If your list contains the same CURP repeated, it is only looked up once. Duplicates get the same result without being billed twice.
- Shared cache benefits. If any CURP in the batch was already looked up before (by you or by another part of your system), it is delivered from cache instantly and at no extra charge.
- Cancellable. If you realize you sent the wrong batch, you can cancel it. Anything already processed is kept; the rest is released.
- Labels for easy correlation. Every item can carry your own label (the internal employee, customer or case ID). When you read the results, you instantly know which record in your own database each response maps to.
- You only pay for real validations. Cache hits are free, not-found results are free. You only pay for the lookups that actually queried the official registry.
Real-world use cases
Batch processing becomes useful in a wide range of scenarios where the only previous option was rolling your own orchestration:
- Employee onboarding. When your company hires a large group — a shift change, a temporary project, a peak season — you validate every CURP on the new payroll in one go.
- Database cleanup. If you inherited a customer database of questionable quality, you can validate every CURP on file to detect typos or outdated records.
- Compliance and KYC. Know-Your-Customer processes at fintechs, banks, insurance companies and regulated platforms: validate entire batches of new customers against the official registry.
- Healthcare and education. Hospitals, clinics, schools and universities can validate complete patient or student records in a single operation.
- Government programs. Public agencies receiving beneficiary lists can validate them in batch before processing payments or deliveries.
- Collections and portfolio verification. Collections companies can validate debtor batches to confirm identities and refresh data before starting outreach.
- System migrations. When you migrate data between two systems, validate the whole portfolio in one batch to spot inconsistencies before the cutover.
What you already have keeps working
If your system today uses the single-lookup /v1/curp endpoint, you don't need to change anything. That endpoint is still available with the same contract and the same latency. The batch endpoint is an additional option for the cases where you need volume.
You can even combine the two: use the single-lookup endpoint for interactive validations (a web form where a user types a CURP and waits for the immediate answer) and the batch endpoint for background mass processing (nightly jobs, file imports, list validation).
Next steps
The batch processing endpoint is available to all API users today. If you don't have an API key yet, you can sign up and get one in minutes. Your first run can be your own CURP — the full documentation walks you through every step.