Policy Linking and De-linking

Link and de-link ABHA policies for NHCX payers and TPAs with the required payer and processor identifiers.

Each payer must create its own participant. This rule applies even if the payer uses a TPA.

For a direct payer, set payerid to the payer participant code. For a TPA case, set payerid to the insurer code.

Set processingid to the TPA participant code when a TPA processes the policy.

If an insurer changes its TPA, de-link the old policies first. Then link the policies with the new processingid.

Environment base URLs

Environment	`envBaseUrl`
Sandbox	`https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice`
Production	`https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`

Use the base URL once. Do not add participanthcxservice twice.

Link a policy

POST{envBaseUrl}/participant/link/abha/policy

Link one or more policies to an ABHA number.

Link request

Policy link request

{
  "requestid": "e011c4a2-xxxx-xxxx-xxxx-50d06af51555",
  "abhanumber": "12345678910111",
  "mobilenumber": "1234567890",
  "memberid": "Cust00",
  "payerid": "XXXXXX@sbx",
  "processingid": "XXXXXX@sbx",
  "policies": [
    {
      "productid": "Prod01",
      "productname": "Active Assure"
    },
    {
      "productid": "Prod02",
      "productname": "Life Insurance Policy"
    }
  ]
}

De-link a policy

POST{envBaseUrl}/participant/delink/abha/policy

De-link one or more policies from an ABHA number.

Verify the caller before de-linking

Only the payerid participant or the processingid participant can de-link a policy.

De-link request

Policy de-link request

{
  "requestid": "5f314cf3-xxxx-xxxx-xxxx-585b5d7d0bc0",
  "payerid": "XXXXXXXX@sbx",
  "memberid": "Cust00",
  "policies": [
    {
      "productid": "Prod01",
      "productname": "Active Assure"
    }
  ]
}

Validation rules

Process	Validation	Error result
Policy link	Each payer must have an individual participant code.	NHCX rejects an unknown payer code.
Policy link	A TPA case must send the insurer code as `payerid`.	NHCX cannot map the insurer.
Policy link	A TPA case must send the TPA code as `processingid`.	NHCX cannot map the processor.
TPA change	The participant must de-link old policies before a new TPA link.	The old processor can remain active.
Policy de-link	The token client ID must match `payerid` or `processingid`.	NHCX rejects the request.
Policy de-link	The policy must exist in the linked policy list.	NHCX returns `There is no policy with requested details`.

API implementation details

NHCX extracts the client ID from the access token during de-link.

NHCX compares the client ID with the participant that registered the insurer.

NHCX also compares the client ID with the TPA participant in processingid.

NHCX allows de-link only when one comparison matches.

Use Sandbox Onboarding to create test participant codes.

Sources

policy-linking-and-delinking.md (NHCX policy linking guide)

PreviousEncryption Certificate Next Provider Use Cases