Get a fiscal validation
LiveServed by the v1 API in development with the same checks as production; production opens on the same contract. The capabilities from before v1 keep running in production at the path your account team gives you.
Use it if you missed a webhook.
Needs the fiscal_validations:read scope.
oauth2 fiscal_validations:readAuthorizationBearer <token>OAuth 2.0 client credentials. Exchange your client_id and client_secret at /oauth/token of the environment for a bearer token valid for one hour. The playground of every operation asks for your own client and keeps it in your browser tab only.
Scope: fiscal_validations:read
id*stringThe fiscal validation id.
^fv_[0-7][0-9a-hjkmnp-tv-z]{25}$OK
application/json- response
id*string^fv_[0-7][0-9a-hjkmnp-tv-z]{25}$external_id*stringYour own id for this person, merchant or record. Echoed back in every response and webhook.
length <= 128status*stringreceived when heru accepts the request, processing while it queries the SAT, then completed, partially_completed or failed. completed means the SAT answered, even when the answer is that the CURP or the RFC does not exist: code says so. partially_completed means some SAT sources did not answer; heru retries automatically and sends another webhook when it completes. failed means heru could not finish the validation after every retry.
"received""processing""completed""partially_completed""failed"code?stringWhat the SAT answered when it is not a full profile, or why the validation is incomplete. Absent when the validation completed with a full profile. With completed: CURP_NOT_FOUND the CURP is not registered with RENAPO; RFC_NOT_FOUND the RFC is not registered with the SAT; NAME_MISMATCH the name sent does not match the RFC. With partially_completed: SAT_SOURCES_PENDING, some SAT sources did not answer and heru retries. With failed: RETRIES_EXHAUSTED, every retry with the SAT failed. See validation results.
"SAT_SOURCES_PENDING""CURP_NOT_FOUND""RFC_NOT_FOUND""NAME_MISMATCH""RETRIES_EXHAUSTED"message?|nullpending?array<>Sections of result that the SAT has not returned yet. Those sections are null; everything else in result is final. Present when status is completed (always empty) or partially_completed.
result?|Present once the validation finishes. Absent while it is processing. Null when there is no profile to return: the CURP or the RFC does not exist, the name does not match, or the validation failed.
created_at?stringdate-timeupdated_at?stringdate-timecurl -X GET 'https://api.dev.b2b.heru.app/v1/fiscal-validations/fv_01m4ra8vqve0xv4yfe92canf5a'{ "id": "fv_01m4ra8vqve0xv4yfe92canf5a", "external_id": "FV-2026-004413", "status": "completed", "message": null, "pending": [], "result": { "curp": "HEGL900101HDFRRS06", "name": "JOSE LUIS HERNANDEZ GARCIA", "given_names": "JOSE LUIS", "first_surname": "HERNANDEZ", "second_surname": "GARCIA", "rfc": "HEGL900101K44", "rfc_valid": true, "rfc_active": true, "postal_code": "06600", "regimes": [ { "code": "625", "description": "Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas" } ], "efirma": { "active": true, "valid_from": "2024-03-02", "valid_to": "2028-03-02" }, "csd": { "active": false, "valid_from": null, "valid_to": null }, "third_party_invoicing": { "eligible": true, "reason": null }, "validation_url": "https://siat.sat.gob.mx/app/qr/faces/pages/mobile/validadorqr.jsf?D1=10&D2=1&D3=89097221992_HEGL900101K44" }, "created_at": "2026-10-12T15:04:05.115Z", "updated_at": "2026-10-12T15:04:41.203Z"}List fiscal validationsGET
Most recent first. Needs the `fiscal_validations:read` scope.
Find or register a person's NSSPOST
Looks up the person's Número de Seguridad Social with the IMSS. With `register_if_missing`, starts the registration when they have none. Asynchronous; the result arrives by webhook. If the IMSS asks for in-person validation, the validation fails with `code` `IN_PERSON_VALIDATION_REQUIRED` and the worker must go to an IMSS office. Needs the `social_security_validations:write` scope.