Skip to main content

Onboarding

Participant create (v2)

Registry-linked creation: registry type and ID, role codes, endpoint URL and contacts; returns participantid and a transactionid for /validate.

POST/v2/participant/create

### Business purpose

Production onboarding needs to prove that the organisation registering on NHCX is the same one already known to an external authority (the ABDM Health Facility Registry for hospitals, the IRDAI registry for insurers and TPAs). The v2 create therefore takes a thin, registry-linked payload rather than a full profile, validates the mobile number against the number held in HFR or the NHCX payer details, and sends a one-time passcode to that number. This is step 1 of the four-step production sequence and is what turns a verified facility into an addressable NHCX participant.

### When to use

Use at production onboarding after sandbox certification has been reviewed and credentials issued; the documented URL is https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/participant/create. It is always followed by GET /validate with the returned transactionid and the SMS passcode, which must happen within 24 hours. In the sandbox the FAQ lists the unversioned /participant/create instead. No NHCX workflow codes or x-hcx-status values apply; this is a synchronous JSON call outside the JWE protocol.

### Preconditions

- Production (or sandbox) credentials and a fresh Bearer token in bearer_auth with the Bearer prefix; Accept and Content-Type set to application/json. - registrytype from the Valid Registry Enums: HFR 10001, NIN 10002, ROHINI 10003, PAYER 10004 (HFR/EUA use 10001, PAYER/TPA use 10004). - role as an array from the Valid Role Enums: PROVIDER 10001, PAYER 10002, AGENCY_TPA 10003, EUA 10009, among others. - registryid formatted correctly: HFR ID for providers; IRDAI ID with leading zeros stripped for payers. - mobilenumber already registered with HFR (providers) or NHCX payer details (payers); both must match for the call to succeed. - Required fields: registrytype, registryid, role, endpointurl, mobilenumber, email; scheme_code is optional.

### Postconditions

HTTP 200 with ParticipantCreateV2Resp: participantid, facilityname, facilitycontact and facilityemail echoed from the linked registry, a transactionid such as 1vouv8tlz2tnl-1fpspjhwj07c6, and an error object (code, message, trace). A passcode is sent by SMS to the registered mobile number. The participant is not confirmed until GET /validate?transactionId=&passcode= succeeds; the transaction id and passcode are valid for 24 hours and each re-trigger generates a new pair. Only after creation confirmation can /v2/participant/update be used to upload the certificate and endpoint. Failures use the standard 400/404/500 ErrorResponse envelope.

### Common mistakes

- Confusing the two 10001 enums: 10001 is PROVIDER as a role and HFR/EUA as a registry type; they are different fields. - Sending the IRDAI registry ID with leading zeros (0123 instead of 123), which the NHA lists as a frequent production failure. - Using a mobile number that does not match the one on record in HFR or the NHCX payer details; the validation requires an exact match. - Losing the transactionid: if it is forgotten, the only recovery is to create the request again, which issues a new passcode. - Letting the 24-hour validity lapse before calling /validate. - Sending the v1 snake_case body or expecting a participant_code key; this response uses participantid.

### Best practices

- Persist transactionid immediately, together with the timestamp, so the /validate step can be completed by whoever holds the registered phone. - Verify the mobile number and registry ID against HFR or IRDAI records before calling; the check is strict and every failed attempt is a manual round trip. - Treat the error object in a 200 response as meaningful and surface it to the operator rather than assuming success from the HTTP status alone. - Do not retry blindly: each call generates a new transaction id and passcode and invalidates the plan to confirm the previous one. - Keep sandbox and production credentials, hosts and participant codes strictly separate.

### Related scenario

An insurer's TPA has cleared sandbox certification and received production credentials. Its integrator obtains a Bearer token, then calls /v2/participant/create with registrytype 10004, the IRDAI-issued registry ID (leading zeros stripped), role ["10003"], the production callback base URL and the mobile number the NHA has on file. The response returns participantid, the facility details and transactionid 1vouv8tlz2tnl-1fpspjhwj07c6, and an SMS passcode reaches the compliance officer's phone. Within the hour the team calls GET /validate with both values to confirm creation, then proceeds to /v2/participant/update to publish its encryption certificate.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

Authorizations

Authorizationbearer tokenRequired

On every NHCX call, the token goes in a header called bearer_auth, with the word Bearer and a space in front. The sources are not unanimous: the authentication page and the FAQ both write the example as Authorization, and the notification endpoint uses Authorization. The safe course, and what the adapter does, is to send both headers with the same value.

Headers

bearer_authstringRequired

It is bearer_auth, not Authorization, on NHCX's own endpoints.

Body

registrytypestring
registryidstring
rolestring[]
endpointurlstring
mobilenumberstring
emailstring

Responses

200

HTTP 200 with ParticipantCreateV2Resp: participantid, facilityname, facilitycontact and facilityemail echoed from the linked registry, a transactionid such as 1vouv8tlz2tnl-1fpspjhwj07c6, and an error object (code, message, trace).