Skip to main content

Participant registry

Link payer product

Registers a product (product id and name) against a payer's participant code, so that it can be referenced in ABHA policy links.

POST/product/link

### Business purpose

Products are the payer's catalogue entries that policies[].productid and productname refer to when a beneficiary is linked. This Retrieving API call, described in the OpenAPI document as the API to list products by the payers or insurance companies, is how an insurer places a product in the registry under its own participant code. Doing so makes the product ownership resolvable through /product/getowner and gives providers a stable productId and productName to match against when they resolve coverage for InsurancePlan and preauth.

### When to use

Use it when a payer introduces a new product, and before any /participant/link/abha/policy call that references that product. It is part of payer-side catalogue setup, ahead of member linking and well ahead of any claim-side workflow. When a product is retired, the counterpart /product/delink removes it. The documentation does not describe versioning or renaming of products; treat a rename as de-link and re-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 payer or insurance company must already be a registered participant with its own participant code. - Body is ProductLinkRequest with all three fields required: productid, productname and participantcode.

### Postconditions

On success the endpoint returns HTTP 200 with ParticipantCreateResponse, whose single optional field participant_code is the machine-generated participant identifier on the HCX instance. No callback follows. The product becomes the value that /product/getowner resolves back to the owning participant and that policy links refer to. Failures return 400, 404 or 500 with the ErrorResponse envelope (timestamp plus Error with code, message and trace).

### Common mistakes

- Omitting one of the three required fields; productid, productname and participantcode are all mandatory. - Using a participantcode in the wrong casing or from the wrong environment (sandbox codes look like 100001@sbx, production codes end in @hcx). - Referencing a product in a policy link before it has been linked here, so provider-side product matching later fails. - Expecting product details in the response; only participant_code is returned. - Missing the Accept header or the Bearer prefix on bearer_auth.

### Best practices

- Keep productid values stable and unique within the payer; providers use productId for product-level matching and productName as the practical policy or coverage code for plan lookup. - Register products before linking members, and verify with /product/getowner that the product resolves to your participant code. - Log the participant_code returned with the product identifiers for reconciliation. - Refresh the Bearer token proactively and retry once on 401.

### Related scenario

An insurer launches a new family floater plan. Before its policy administration system can link any member, it calls /product/link with the product id, the product name that hospitals will see, and the insurer's participant code, receiving its participant_code back in the response. It then checks /product/getowner with the product id to confirm ownership, and begins linking members with /participant/link/abha/policy. Hospitals that later call /participant/get/policies will see the product id and name, use productName for the InsurancePlan lookup and productId for coverage matching in the preauth.

### Specification

Chapter [Participants and policies](/docs/nhcx/v1/registries) 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

productidstring
productnamestring
participantcodestring

Responses

200

On success the endpoint returns HTTP 200 with ParticipantCreateResponse, whose single optional field participant_code is the machine-generated participant identifier on the HCX instance.