Find or register a person's NSS
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.
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.
oauth2 social_security_validations:writeAuthorizationBearer <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:write
Idempotency-Key*stringUnique per operation. Retrying with the same key returns the original result for 24 hours.
length <= 255application/json- body
curp*stringCURP, 18 characters.
^[A-Z]{4}[0-9]{6}[HM][A-Z]{5}[A-Z0-9][0-9]$external_id*stringYour own id for this person, merchant or record. Echoed back in every response and webhook.
length <= 128register_if_missing?booleanIf the person has no NSS, start the IMSS registration.
falsepostal_code?stringRequired when register_if_missing is true.
Accepted
application/json- response
Acknowledgement that heru accepted the validation. Read the full validation with GET or wait for the webhook.
id*string^ssv_[0-7][0-9a-hjkmnp-tv-z]{25}$status*"received""received"message*stringcreated_at*stringdate-timecurl -X POST 'https://api.dev.b2b.heru.app/v1/social-security-validations' \ -H 'Idempotency-Key: try-it-0001' \ -H 'Content-Type: application/json' \ -d '{ "curp": "HEGL900101HDFRRS06", "external_id": "SSV-2026-001213", "register_if_missing": true, "postal_code": "06600"}'{ "id": "ssv_01m4ra8vtnepvrtmxdf6v3atq2", "status": "received", "message": "Request successfully accepted for processing", "created_at": "2026-10-12T15:04:05.205Z"}