Register a worker
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.
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.
oauth2 workers: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: workers:write
Idempotency-Key*stringUnique per operation. Retrying with the same key returns the original result for 24 hours.
length <= 255application/json- body
external_id*stringYour id for this worker, e.g. their driver number. Unique per company, and echoed back in every response and webhook.
length <= 128curp*stringCURP, 18 characters.
^[A-Z]{4}[0-9]{6}[HM][A-Z]{5}[A-Z0-9][0-9]$email?stringheru can send the enrollment link and expiry reminders here.
emailphone?stringE.164, e.g. +525512345678. heru can send the enrollment link by SMS.
services?array<>What you will do with the worker. It decides what the enrollment page asks for (efirma, csd and invoicing need their e.firma; the rest only need consent) and when the worker is ready.
Created
application/json- response
id*string^wrk_[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*stringpending until the worker completes the enrollment page; in_progress while heru validates them with the SAT or requests their CSD; ready when every service you enabled is in order; blocked when the worker has something to do, listed in open_actions; not_evaluated when the worker has no service that heru checks; removed after DELETE /workers/{id}.
"ready""pending""in_progress""blocked""not_evaluated""removed"curp*stringCURP, 18 characters.
^[A-Z]{4}[0-9]{6}[HM][A-Z]{5}[A-Z0-9][0-9]$rfc?|nullname?|Name as registered with the SAT, once heru validated the worker.
postal_code?|Postal code of the tax address.
regimes?array<>services*array<>The services you enabled for the worker. ready means all of them are in order.
efirma*csd*open_actions*array<>What the worker must do before they are ready: give_consent and upload_efirma on the enrollment page; renew_efirma when their e.firma expired; confirm_regime when their tax regime does not allow the services you enabled; update_postal_code when their tax address changed with the SAT. Empty when there is nothing to do.
enrollment*consent_at?|When the worker accepted heru's terms and privacy notice on the enrollment page. Null until then.
compliant_at?|When the worker last became ready. Null if they have never been.
created_at*stringWhen you registered the worker.
date-timeupdated_at*stringLast change of any field. Use it with updated_since in the workers feed.
date-timeremoved_at?|When you removed the worker. Null while active.
curl -X POST 'https://api.dev.b2b.heru.app/v1/workers' \ -H 'Idempotency-Key: try-it-0001' \ -H 'Content-Type: application/json' \ -d '{ "external_id": "DRV-000088213", "curp": "HEGL900101HDFRRS06", "phone": "+525512345678", "services": [ "fiscal_validation", "efirma", "invoicing" ]}'{ "id": "wrk_01m4ra8w0he5esnnsew0v9ffkv", "external_id": "DRV-000088213", "status": "pending", "curp": "HEGL900101HDFRRS06", "rfc": null, "name": null, "postal_code": null, "regimes": [], "services": [ "fiscal_validation", "efirma", "invoicing" ], "efirma": { "active": false, "valid_from": null, "valid_to": null }, "csd": { "active": false, "valid_from": null, "valid_to": null }, "open_actions": [ "give_consent", "upload_efirma" ], "enrollment": { "status": "pending", "url": "https://enroll.heru.app/w/Rk7pX2mQ9vLc4TzN8bWy?expires=1792160571&signature=9f2c7a41e8", "expires_at": "2026-10-16T14:22:51.604Z", "completed_at": null }, "consent_at": null, "compliant_at": null, "created_at": "2026-10-09T14:22:51.604Z", "updated_at": "2026-10-09T14:22:51.604Z", "removed_at": null}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.
Create an enrollment linkPOST
Creates a new signed enrollment link for the worker, valid for 7 days. Any previous link stops working. Use it when the first link expired, or when the worker has something to do again, such as renewing their e.firma (`renew_efirma`). The current link always comes in `enrollment` when you get the worker. Needs the `workers:write` scope.