FAQs

These FAQs summarize common NHCX technical questions. Use them with the official sandbox portal and your latest certification notes.

Participant setup

What is a registry ID in the NHCX Participant API?

A registry ID is the unique identifier from an authorized external registry. NHCX uses it to identify a provider, payer, TPA, or EUA. Send it during participant setup and transactions.

Which registry ID applies to each participant type?

What role codes apply in sandbox and production?

What registry codes apply in sandbox and production?

Why does correct role and registry map matter?

An incorrect map can cause access issues. It can also cause request rejection or route transactions to the wrong participant.

Can an entity have multiple participant IDs?

Yes. An entity can have multiple participant IDs. Link each participant ID to a separate HFR ID.

Sandbox endpoints

What are the provider sandbox base URLs?

How can I generate a sandbox session token?

Call the ABDM session API with your sandbox client credentials.

curl --request POST 'https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions' \
  --header 'Content-Type: application/json' \
  --header 'REQUEST-ID: bd515183-a512-4324-be14-f18754730f3e' \
  --header 'TIMESTAMP: 2026-04-28T11:55:45.915Z' \
  --header 'X-CM-ID: sbx' \
  --data-raw '{
    "clientId": "SANDBOX_CLIENT_ID",
    "clientSecret": "SANDBOX_CLIENT_SECRET",
    "grantType": "client_credentials"
  }'

How can I generate a production session token?

Call the ABDM session API with your production client credentials. Verify the correct X-CM-ID value before production use.

curl --request POST 'https://apis.abdm.gov.in/api/hiecm/gateway/v3/sessions' \
  --header 'Content-Type: application/json' \
  --header 'REQUEST-ID: f51f71c3-020e-423b-a1b1-49b0f25cd553' \
  --header 'TIMESTAMP: 2026-04-28T11:57:09.472Z' \
  --header 'X-CM-ID: sbx' \
  --data-raw '{
    "clientId": "PRODUCTION_CLIENT_ID",
    "clientSecret": "PRODUCTION_CLIENT_SECRET",
    "grantType": "client_credentials"
  }'

Request headers and security

Why does a 401 Unauthorized error appear after an API call?

The token can expire. The bearer_auth header can also contain an invalid token. Generate a new token and retry the API call.

What values apply to x-hcx-api_call_id, x-hcx-request_id, and x-hcx-correlation_id?

Use a random 36-character UUID for each field. Use a new correlation ID for each request cycle.

Example UUID: d9f1a2c2-e3b6-49f9-8c2d-071b13ba85ab.

What timestamp format applies to x-hcx-timestamp?

Use the current UTC timestamp in ISO format. Use this format: YYYY-MM-DD'T'HH:mm:ss.SSS'Z'.

Example: 2024-05-20T11:29:27.358Z.

How does NHCX secure request data?

NHCX requires JWE Compact Serialization for each request sent to NHCX. The JWE protected header contains standard JWE fields and x-hcx-* metadata. This design provides confidentiality, integrity, and traceability.

Protocol behavior

Does NHCX support synchronous responses for use case requests?

No. NHCX use case communication is asynchronous. Providers must implement callback endpoints for payer responses. NHCX does not return a synchronous FHIR decision.

What must provider callback endpoints do?

A provider callback endpoint must return HTTP 202 within 30 seconds. If NHCX does not receive HTTP 202, the gateway retries the callback.

Why should providers integrate the InsurancePlan API?

The InsurancePlan API shows benefit rules before preauthorization. It can identify required documents before submission. It reduces rework and rejection rates. It can help payers approve requests faster.

Dummy payer and test tools

What is dummy payer 1000003538@hcx?

The dummy payer is a sandbox insurance payer for tests. Use it to test provider flows before payer tests. See Dummy Payer.

Where can I find the NHCX integration documents?

Open the NHCX document portal at https://hcxsbx.abdm.gov.in/#/documents.

Where can I find the NHCX-PMJAY documents?

Open the NHCX-PMJAY document portal at https://hcxsbx.abdm.gov.in/#/hmisdocuments.

What is the difference between regular NHCX and PMJAY-NHCX?

Regular NHCX supports private insurance flows for providers, payers, and TPAs. PMJAY-NHCX extends the same framework for government health schemes. PMJAY-NHCX can require extra scheme setup and workflow alignment.

Problem fixes

Why does bio auth return error K-547?

Set lr to Y. Keep the other attributes as specified by the source.

Create the text value as 2.5 plus ra, rc, lr, de, and pfr. Convert the text value to SHA-256. Encode the SHA-256 hash to Base64 to create wadh.

When does 401 Unauthorized with sender not authorized occur?

This error occurs when the session token expires. Generate a new session token and retry the API call.

Why do callbacks not reach my server?

Check these items first.