Participant registry

Link ABHA number to policies (V2)

V2 variant of the ABHA policy link; same ParticipantLinkAbhaRequest body and ParticipantLinkAbhaResponse as the unversioned call.

### Business purpose

This endpoint serves the same business need as /participant/link/abha/policy: it lets a payer (or the TPA processing on its behalf) record which products a beneficiary holds, keyed by ABHA number and member id, so that providers can discover the policy and route claims correctly. The OpenAPI document exposes it as operation participantLinkAbhaPolicyV2 with an identical request and response schema to the v1 path; the documentation does not describe any behavioural difference beyond the path and operationId.

### When to use

Use it in exactly the situations where the v1 link call applies: policy issue, renewal, member addition, or re-linking after a de-link when a payer changes TPA. It belongs to the member-layer setup that precedes every claim-side workflow (coverage eligibility, preauthorisation with workflow code 12, enhancement with code 13, claim). Choose this path or the v1 path consistently across your integration; the docs give no reason to mix them.

### 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 token must belong to the participant named as payerid or processingid, generated with the client_id used at participant creation. - Note the capital V in the path (/V2/participant/...), which differs from the lower-case /v2/ used by the init and validate variants.

### Postconditions

A successful call returns HTTP 200 with ParticipantLinkAbhaResponse (optional result string and optional errormessage with errorcode and errordescription). No asynchronous callback follows; the beneficiary's products are immediately discoverable through /participant/get/policies or /V2/participant/get/policies. Errors come back as 400, 404 or 500 with the registry ErrorResponse envelope. The link can later be reversed only through the de-link endpoints, which check that the caller is the payerid or processingid participant.

### 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). - Lower-casing the path to /v2/participant/link/abha/policy, which is not the same route; the lower-case /v2/ prefix belongs to the init and validate pair.

### 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 TPA that processes claims for several insurers migrates its integration to the V2 participant APIs. When one of its insurers issues a new individual health policy, the TPA's system calls /V2/participant/link/abha/policy with the insurer's participant code as payerid and its own code as processingid, listing the product from the insurer's catalogue. The TPA then confirms the link with /V2/participant/get/policies using the member's ABHA number. When the beneficiary later visits a hospital, the provider resolves the processingid as the receiver code and submits the coverage-eligibility check and preauthorisation to the TPA.

### Specification

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