Skip to main content

Onboarding

Participant create (v1)

Creates a participant record in the NHCX registry from a full v1 profile and returns the generated participant_code.

POST/participant/create

### Business purpose

Nothing moves through NHCX until both the sender and the recipient exist in the participant registry, which the platform treats as the source of truth for who may exchange claims data. This call is the original, full-profile way to register a hospital, insurer or TPA: it captures the organisation's name, roles, contact points, linked registry identifiers, callback endpoint and public encryption certificate in one record. The registry then issues the participant_code that every later transaction is addressed with.

### When to use

Call it once, at onboarding time, before any transaction API is attempted. The FAQ base-URL table lists this path (not the v2 form) as the sandbox Create Participant API at https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/create, whereas production onboarding is documented against /v2/participant/create followed by GET /validate. It is a plain synchronous registry call; no NHCX workflow or x-hcx-status codes are involved. If the organisation later rotates its certificate or moves its callback URL, use /participant/update or /v2/update/cert rather than creating again.

### Preconditions

- Sandbox or production access has been granted through the semi-manual registration review, so you hold a client_id and client_secret. - A valid Bearer token from POST /get/session, sent with the Bearer prefix in the bearer_auth (Authorization) header, plus Accept: application/json and Content-Type: application/json. - Required body fields of ParticipantCreateBody: linked_registry_codes, participant_name, registryid, roles, primaryEmail, primaryMobile, encryption_cert and endpoint_url. The certificate is mandatory at creation, so generate the 2048-bit RSA key pair and self-signed X.509 certificate first and Base64-encode it. - Correct registry ID for your type: HFR ID for providers, IRDAI-issued ID for payers and TPAs.

### Postconditions

On success the registry returns HTTP 200 with ParticipantCreateResponse containing only participant_code, described as the machine-generated unique identifier of the participant on the HCX instance; sandbox codes look like 100001@sbx and production codes like XXXXX7583@hcx. There is no asynchronous callback. The new record carries a status (Created, Active, Inactive or Blocked in the architecture description) that the gateway checks on every routing leg, so the code is not usable for transactions until the instance activates it. Failures return 400 Client Error, 404 Resource not found or 500 with the ErrorResponse envelope (timestamp plus error code, message and trace).

### Common mistakes

- Passing the wrong registry ID: providers must send the HFR ID, payers the IRDAI ID with leading zeros stripped (0123 becomes 123). - Mixing field casing across generations: this v1 body is snake_case (participant_code, encryption_cert, endpoint_url); copying v2 names such as endpointurl yields a 400. - Omitting the Accept header or the Bearer prefix on the token, which surfaces as a rejection before business logic or a flat 401. - Registering an endpoint_url that is an IP address or carries a port; the callback URL must be a domain name on an India-based server with the NHCX NAT IPs whitelisted. - Submitting the raw PEM instead of the Base64-encoded certificate.

### Best practices

- Keep the private key generated alongside the certificate in PKCS8 form locally; only the certificate (public half) is registered. - Store the returned participant_code as configuration; it becomes x-hcx-sender_code on every outbound message and the value payers use in /fetch/certs. - Do not re-run create to fix a field; the registry is updated with /participant/update, and an entity can legitimately hold several participant codes only when each is linked to a separate HFR ID. - Log the request minus the certificate body and never log the bearer token or client_secret. - Treat host and prefix as one environment variable; sandbox codes and credentials do not carry into production.

### Related scenario

A 200-bed hospital has been approved for the NHCX sandbox and received its client credentials. The integration team first calls POST /get/session to obtain a Bearer token, then generates an RSA key pair and self-signed certificate. They call /participant/create with the hospital's HFR ID as registryid, role PROVIDER, the Base64 certificate and their callback base URL. The registry returns participant_code 100001@sbx. With that code in hand the team calls /fetch/participants/list to find the dummy payer 1000003538@hcx and /fetch/certs to obtain its certificate, and only then sends the first /v1/coverageeligibility/check.

### 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.

sourcestringRequired

Sent on this call, as the package's request carries it.

Body

linked_registry_codesstring[]
registryidstring
participant_namestring
scheme_codestring
statestring
districtstring
rolesstring[]
primaryEmailstring
phonestring[]
primaryMobilestring
signing_cert_pathstring
encryption_certstring
endpoint_urlstring

Responses

200

On success the registry returns HTTP 200 with ParticipantCreateResponse containing only participant_code, described as the machine-generated unique identifier of the participant on the HCX instance; sandbox codes look like 100001@sbx and production codes like XXXXX7583@hcx.