Get your sandbox credentials
Every National Health Claims Exchange (NHCX) call carries a session token, and every token starts with an ABDM client ID and client secret. This chapter gets you those credentials, your NHCX sandbox roles, and a payer to test against.
In short
- Register your organisation first: a hospital in the Health Facility Registry (HFR), an insurer or TPA with its IRDAI registry id.
- Apply for ABDM sandbox credentials, then register the same client on the NHCX sandbox.
- Your software must support ABDM Milestone 1, ABHA creation and verification.
- Test against the dummy payer, participant code
1000003538@hcx. - The reviews have no fixed turnaround time, so start them first.
Prerequisites
- Your organisation, and a mobile number for its registry record that you can receive messages on.
1. Register the organisation
| You are | Register in | Your registry id |
|---|---|---|
| A hospital or clinic | The Health Facility Registry (HFR), at https://facility.abdm.gov.in/ | The HFR ID |
| A payer or TPA | IRDAI, or the relevant authority | The id that authority issues |
Keep the mobile number on the registry record current. Participant creation checks it and sends a passcode to it.
2. Apply for ABDM sandbox credentials
- Apply at https://sandbox.abdm.gov.in/sandbox/v3/.
- Select "Providers and Payer" and Milestone 1 as your intent.
- Wait for review. On approval you receive a client ID and a client secret.
The review is semi-manual. It filters out repeat requests from one organisation, organisations missing from every registry, technology providers without a valid website, and spam. Send one application only.
Store the secret the way you store any production credential. Never commit it, and never write it to a log.
3. Build Milestone 1
Your software must support ABDM Milestone 1 before it joins NHCX. It creates an ABHA number through Aadhaar or a driving licence. It verifies an ABHA number or ABHA address at patient registration.
4. Register on the NHCX sandbox
Register at https://sandbox.abdm.gov.in/sandbox/v3/sandbox-registration with your ABDM sandbox client ID and secret. When the form is submitted, NHCX sandbox roles are assigned to your client.
Decide your role before you create your participant. A wrong role and registry pair leads to access errors, rejected requests or misrouted messages.
| Role | Role code | Registry | Registry code |
|---|---|---|---|
| Provider | 10001 | HFR | 10001 |
| Payer | 10002 | Payer | 10004 |
| TPA | 10003 | Payer | 10004 |
5. Meet the dummy payer
A provider needs a payer to send requests to. The sandbox has one: the dummy payer, participant code 1000003538@hcx.
| Use case | What you do |
|---|---|
| Coverage eligibility | Send the check. It answers on its own. |
| Insurance plan | Send the request with provider id 32722 and policy number 100217 in the bundle. It answers on its own. |
| Preauthorisation or claim | Send the submit, then choose its answer with the dummy payer action call: Approve, Reject or Query. |
| Payment notice | Start it with the payment notice trigger. |
The provider id and policy number apply to the dummy payer only. Codes such as 100001@sbx and 1000002090@hcx in examples show the format. Before you address any other code, look it up in the participant list.
What you see when it works
- A session token call with your client ID and secret returns an access token.
- The NHCX sandbox registration form is submitted, and roles are assigned to your client.
- Fetching the certificate of
1000003538@hcxreturns a PEM certificate.
When it goes wrong
| What you see | What to do |
|---|---|
| The sandbox application is still in review | Wait. A second application is filtered out as a repeat. Ask about a stalled request at the address below. |
| "No user role found/associated for sender code." | Your client has no NHCX role yet. Confirm the sandbox registration form went through, then write to support. |
| Participant creation fails the mobile number check | The number must match the HFR record, or the payer record. Update the registry record first. |
| Requests are rejected or misrouted after registration | Check the role and registry codes you registered with. |
| The dummy payer sends nothing after a preauthorisation or claim | It waits for the action call. Send it with the correlation ID of your submit. |
Where to get help
| Topic | Write to |
|---|---|
| Fast Healthcare Interoperability Resources (FHIR) bundle validation at sandbox exit, and the internal and Health Tech Committee (HTC) demos | hcx.integration@nha.gov.in |
| Building a FHIR bundle, and the NRCeS specifications | nrc-help@cdac.in |
| ABDM Milestone 1 integration | integration.support@nha.gov.in |
| Facility registration in the HFR | facility@nha.gov.in |
Put your participant code, the environment, the use case and the path in the message. Add the x-hcx-correlation_id, x-hcx-api_call_id and x-hcx-timestamp of the failing request. Quote the error exactly as returned. Replies have no fixed turnaround time.
Next steps
- Quickstart: your first three calls, with nothing but these credentials.
- Base URLs: every address in the sandbox and in production.
- Creating and Updating a Participant: your own participant code.