Get a social security 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.
Returns the validation. Once it completes, result carries the NSS and the person's data; when it fails, code and message say why.
Needs the social_security_validations:read scope.
oauth2 social_security_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: social_security_validations:read
id*stringThe social security validation id.
^ssv_[0-7][0-9a-hjkmnp-tv-z]{25}$OK
application/json- response
id*string^ssv_[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 IMSS (and while a registration started with register_if_missing is in progress), then completed or failed. completed means the IMSS answered, even when the answer is that the person has no NSS or must go in person: code says so. failed means heru could not finish after every retry.
"received""processing""completed""failed"code?stringWhat the IMSS answered when it is not an NSS, or why the validation failed. Absent when the NSS was found. With completed: IN_PERSON_VALIDATION_REQUIRED the IMSS asks the person to go to their subdelegación; REGISTRATION_REQUIRED the person has no NSS, validate again with register_if_missing; CURP_NOT_FOUND the CURP is not registered with RENAPO. With failed: RETRIES_EXHAUSTED, the IMSS did not answer after every retry. See validation results.
"CURP_NOT_FOUND""REGISTRATION_REQUIRED""IN_PERSON_VALIDATION_REQUIRED""RETRIES_EXHAUSTED"message?|nullresult?|Present once the validation finishes. Absent while it is processing. Null when there is no NSS to return.
created_at?stringdate-timeupdated_at?stringdate-timecurl -X GET 'https://api.dev.b2b.heru.app/v1/social-security-validations/ssv_01m4ra8vtnepvrtmxdf6v3atq2'{ "id": "ssv_01m4ra8vtnepvrtmxdf6v3atq2", "external_id": "SSV-2026-001213", "status": "completed", "message": null, "result": { "curp": "HEGL900101HDFRRS06", "nss": "00000000011", "name": "JOSE LUIS HERNANDEZ GARCIA", "given_names": "JOSE LUIS", "first_surname": "HERNANDEZ", "second_surname": "GARCIA", "sex": "H", "birth_date": "1990-01-01", "birth_state": "NE", "documents": { "nss_proof": { "url": "https://download.heru.app/nss-proofs/ssv_01m4ra8vtnepvrtmxdf6v3atq2.pdf?expires=…&signature=…", "expires_at": "2026-10-13T15:06:10Z", "content_type": "application/pdf", "filename": "constancia-nss.pdf" }, "nss_card": { "url": "https://download.heru.app/nss-cards/ssv_01m4ra8vtnepvrtmxdf6v3atq2.pdf?expires=…&signature=…", "expires_at": "2026-10-13T15:06:10Z", "content_type": "application/pdf", "filename": "tarjeta-nss.pdf" } } }, "created_at": "2026-10-12T15:04:05.205Z", "updated_at": "2026-10-12T15:06:10.293Z"}List social security validationsGET
Most recent first. Needs the `social_security_validations:read` scope.
Register a workerPOST
Registers the person and returns `enrollment.url`, a signed link valid for 7 days. There the worker accepts heru's terms and privacy notice and, when the services you enabled need it, uploads their e.firma. Everything that acts on the worker's SAT account (CSD generation and direct invoicing) requires this consent. Needs the `workers:write` scope.