List social security validations
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.
Most recent first.
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
external_id?stringFilter by your id.
curp?stringFilter by CURP.
status?stringreceived, processing, completed or failed.
code?stringFilter failed validations by code.
cursor?stringFrom next_cursor of the previous page.
limit?integer1 to 500.
100OK
application/json- response
data*array<>next_cursor*|nullcurl -X GET 'https://api.dev.b2b.heru.app/v1/social-security-validations'{ "data": [ { "id": "ssv_01m4rb820ae83bwh7g7qv8tdme", "external_id": "SSV-2026-001214", "status": "processing", "message": null, "created_at": "2026-10-12T15:21:07.338Z", "updated_at": "2026-10-12T15:21:07.338Z" }, { "id": "ssv_01m4rb5s17fh2s40s6cv61h9b3", "external_id": "SSV-2026-001220", "status": "failed", "code": "RETRIES_EXHAUSTED", "message": "The IMSS did not answer after every retry", "result": null, "created_at": "2026-10-12T15:19:52.615Z", "updated_at": "2026-10-12T15:20:02.802Z" }, { "id": "ssv_01m4rb38dtf9srah6k22fg54f1", "external_id": "SSV-2026-001217", "status": "failed", "code": "IN_PERSON_VALIDATION_REQUIRED", "message": "The IMSS requires the person to validate in person at an IMSS office", "result": null, "created_at": "2026-10-12T15:18:30.074Z", "updated_at": "2026-10-12T15:18:35.261Z" }, { "id": "ssv_01m4rb0w0nea2r08bgb0y8kw9r", "external_id": "SSV-2026-001215", "status": "failed", "code": "REGISTRATION_REQUIRED", "message": "The person has no NSS; send register_if_missing to start the registration", "result": null, "created_at": "2026-10-12T15:17:11.829Z", "updated_at": "2026-10-12T15:17:17.016Z" }, { "id": "ssv_01m4rays7wffh8b5x7776a3kka", "external_id": "SSV-2026-001221", "status": "failed", "code": "CURP_NOT_FOUND", "message": "The CURP is not registered with RENAPO", "result": null, "created_at": "2026-10-12T15:16:03.452Z", "updated_at": "2026-10-12T15:16:08.639Z" }, { "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" } ], "next_cursor": "eyJiZWZvcmUiOiJzc3ZfMDFtNHJhOHZ0bmVwdnJ0bXhkZjZ2M2F0cTIifQ"}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.
Get a social security validationGET
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.