Participant registry

Link ABHA number to policies

Payer-side write that links a beneficiary's ABHA number and member id to one or more products, so provider policy lookups can find them.

### Business purpose

NHCX does not hold a national policy database of its own. Payers push their beneficiary-to-product links into the participant registry with this call, and providers pull them back with /participant/get/policies. Without a link, a hospital's policy lookup returns nothing and the patient cannot be processed as cashless on NHCX, regardless of what the admission record says. The insurer benefits by making its members discoverable; the hospital benefits by getting the payerId, memberId and productId it needs for every downstream claim call.

### When to use

Use it when a policy is issued or renewed, when a member is added to a product, and after any de-link that must be re-established (for example, when an insurance company moves from one TPA to another). It sits at the very start of the member lifecycle, well before any coverage-eligibility, preauthorisation or claim workflow (workflow codes 12, 121, 13 and so on) is triggered. In the sandbox exit checklist for payers it is use case 1, Link ABHA with Policy, followed by Get Policy and De-Link.

### Preconditions

- A valid Bearer token from the client-credentials call (POST /get/session, form-urlencoded client_id, client_secret, grant_type=client_credentials); tokens last 1200 seconds, so refresh before expiry. - HTTP headers Accept: application/json, Content-Type: application/json and bearer_auth: Bearer <token> (the participant service uses bearer_auth, not Authorization). - Base path for the participant service: https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice (sandbox) or https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice (production). - This is a synchronous plain-JSON registry call: no JWE envelope, no x-hcx-* protocol headers and no correlation id are involved. - The caller must be the participant named as payerid (the insurance company) or as processingid (its TPA), and the token must be minted with the client_id used when that participant was created. - Both the payer and, where applicable, the TPA must already exist in the registry with their own participant codes; every payer has an individual participant code even when it sits under a TPA.

### Postconditions

On success the service returns HTTP 200 with ParticipantLinkAbhaResponse, whose two optional fields are result (a string) and errormessage (errorcode and errordescription). There is no asynchronous callback; the write is immediately visible to /participant/get/policies and /V2/participant/get/policies keyed by ABHA number, member id or mobile number. The linked payerid and processingid become the values that providers later resolve as the payer and the receiver code for NHCX routing. Failures return 400, 404 or 500 with the ErrorResponse envelope (timestamp plus Error with code, message and trace).

### Common mistakes

- Calling with a token minted from a client_id other than the one used at participant creation for the payer or TPA; NHA lists this as common mistake 10 and the call is refused even though the token itself is valid. - Confusing payerid and processingid: payerid is always the insurance company's own participant code; processingid is only the TPA code when the payer is mapped under a TPA. - Trying to move a payer to a new TPA by re-linking in place; the documented path is de-link, then link again with the new TPA's code as processingid. - Omitting one of the required fields (requestid, abhanumber, memberid, payerid, policies with productid and productname) or reusing a non-UUID requestid, which returns 400 with the ErrorResponse envelope. - Sending the token without the Bearer prefix, or omitting the Accept header, both of which reject the call before business logic (401 or 400).

### Best practices

- Generate a fresh UUID for requestid on every call and log it with the response so a duplicate submission can be traced. - Keep the ABHA number in the form the member layer expects (the identifier table and get/policies documentation both specify ABHA without hyphens) and store it in that form. - Make sure productid and productname exactly match the payer's product catalogue as registered through /product/link, because providers will later match on these values. - Cache and proactively refresh the Bearer token; retry once on 401 with a new token, then stop and alert. - After linking, verify the result with /participant/get/policies using the same identifier before telling the provider the member is ready.

### Related scenario

A private insurer onboards a new group policy for a corporate client and issues a family floater to a beneficiary who already holds an ABHA. Its policy administration system has previously registered the product through /product/link and now calls /participant/link/abha/policy with the beneficiary's ABHA number, member id, the insurer's own participant code as payerid and the TPA's code as processingid. A week later the beneficiary is admitted to a network hospital; the hospital's desk calls /participant/get/policies with the ABHA number, receives the linked details and uses the processingid as x-hcx-recipient_code for the coverage-eligibility check and the preauthorisation that follow.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.