Participant registry

Update ABHA number

Replaces a placeholder (dummy) ABHA number with the beneficiary's real ABHA number in the ABHA_AUTH_TRANSACTION table.

POST/update/abhanumber

### Business purpose

Beneficiaries are sometimes onboarded before their real ABHA is known, using a placeholder value. Because the member layer and the Patient resource both key on the ABHA number, a placeholder that is never corrected leaves the beneficiary undiscoverable and breaks the identifier rules for claim bundles. This endpoint, tagged Retrieving API and implemented by updateAbhaNumberController, lets the placeholder be swapped for the real number so that later policy lookups and claim transactions line up. The docs describe it as updating the ABHA number in the ABHA_AUTH_TRANSACTION table.

### When to use

Use it once the beneficiary's genuine ABHA number becomes available after an onboarding that used a dummy value, and before relying on ABHA-keyed policy lookups or building Patient identifiers for coverage-eligibility, preauth (workflow code 12) or claim bundles. The documentation does not restrict which participant role calls it, so treat it as a member-data correction step rather than part of any transaction workflow.

### 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. - Both the placeholder and the real ABHA must be known; the body is UpdateAbhaRequest with two optional strings, dummyAbha and realAbha. - The gateway's error catalogue expects ABHA numbers in XX-XXXX-XXXX-XXXX form (NHCX-1018), while the member layer stores them without hyphens; the docs do not state which form this endpoint expects, so follow your instance's guidance.

### Postconditions

A successful call returns HTTP 200 with UpdateAbhaResponse, which carries optional successMessage and errorMessage strings. Unusually for this service, the 400, 404 and 500 responses also use UpdateAbhaResponse rather than the registry ErrorResponse envelope, so clients must read errorMessage rather than Error.code on failure. No callback follows. After the update, policy lookups and Patient identifiers should use the real ABHA; any provider-side policy cache built on the placeholder needs a forced refresh.

### Common mistakes

- Parsing failures as ErrorResponse; this endpoint returns UpdateAbhaResponse for 400, 404 and 500 as well as for success. - Sending an empty body; both fields are optional in the schema, but the operation is meaningless without dummyAbha and realAbha. - Inconsistent ABHA formatting between systems: NHCX-1018 requires XX-XXXX-XXXX-XXXX at the gateway, while x-hcx-ben-abha-id and the member-layer lookups take the number without hyphens. - Forgetting to refresh cached policies and stored Patient identifiers that still carry the placeholder. - Omitting the Accept header or the Bearer prefix on bearer_auth.

### Best practices

- Record both the placeholder and the real ABHA with the timestamp of the change for audit purposes. - Read successMessage and errorMessage on every response and treat a non-200 status as failure even if the body parses. - Immediately re-run /participant/get/policies with forceRefresh: true for the affected beneficiary. - Keep the ABHA formatting rule per field: hyphen-free for member lookups and x-hcx-ben-abha-id, XX-XXXX-XXXX-XXXX where NHCX-1018 applies. - Never log the token; log the ABHA change with the request identifier only.

### Related scenario

A state scheme enrols a beneficiary in a hurry with a dummy ABHA so that a policy can be linked and an emergency admission can proceed. After discharge the beneficiary completes ABHA creation and the real number is captured. The payer's system calls /update/abhanumber with dummyAbha and realAbha, receives a successMessage, and then calls /participant/get/policies with forceRefresh to make sure the real ABHA resolves the linked product. The hospital's billing team, preparing the final claim, refreshes its own policy cache so that the Claim bundle's Patient identifiers carry the PMJAY member id and the real hyphen-free ABHA.

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

dummyAbhastring

realAbhastring

Responses

200

A successful call returns HTTP 200 with UpdateAbhaResponse, which carries optional successMessage and errorMessage strings.

Update ABHA number

curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/update/abhanumber \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "dummyAbha": "99999999999999",
  "realAbha": "12345678910111"
}'

{
  "successMessage": "ABHA number updated successfully"
}

Generated from the schema. The values are placeholders, not a captured response.