Quickstart

Make your first three National Health Claims Exchange (NHCX) calls with nothing but your sandbox credentials. You get a session token, look up the dummy payer in the participant registry, and fetch the certificate you would seal its messages with.

In short​

• Three calls, in order: session token, participant search, fetch certificate.
• None of them changes anything and none has a callback, so you need no server yet.
• The two registry calls carry the token in bearer_auth, with Bearer and a space in front.
• The counterparty is the sandbox dummy payer, 1000003538@hcx.

Prerequisites​

• An ABDM sandbox client ID and client secret, with NHCX sandbox roles assigned. Get your sandbox credentials if you do not have them.
• A terminal with curl, and a way to generate a universally unique identifier (UUID).
• A clock synchronised with NTP, because the session call carries the current time.

Get a session token​

curl --location --request POST 'https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions' \
  --header 'Content-Type: application/json' \
  --header 'REQUEST-ID: <uuid>' \
  --header 'TIMESTAMP: <iso timestamp>' \
  --header 'X-CM-ID: sbx' \
  --data-raw '{
    "clientId": "<client id>",
    "clientSecret": "<client secret>",
    "grantType": "client_credentials"
  }'

Session token in the API reference

• <client id> and <client secret>: your ABDM sandbox client ID and client secret.
• <uuid> in REQUEST-ID: a fresh UUID you generate for this call. Generate a new one on every call.
• <iso timestamp> in TIMESTAMP: the current UTC time with milliseconds and a trailing Z, such as 2026-09-04T06:15:51.975Z.

You receive HTTP 200 with a non-empty accessToken and expiresIn set to 1200. The token lasts 1200 seconds (20 minutes) from the moment it arrives. Keep it for the next two steps.

Look up the dummy payer​

curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/search' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'bearer_auth: Bearer <access token>' \
  --data-raw '{
    "participant_code": "1518@hcx"
  }'

Participant search in the API reference

• The sample body carries 1518@hcx. Replace it with the code of the participant you are looking up. For the sandbox dummy payer, that is 1000003538@hcx.
• <access token>: the accessToken from step 1.

You receive HTTP 200 with a participants array. Its entry carries the code you sent, its roles and its status. A participant is ready to receive messages when its status is Active, and its endpoint_url and encryption_cert are filled.

Fetch its certificate​

curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/fetch/certs' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'bearer_auth: Bearer <access token>' \
  --data-raw '{
    "participantid": "1518@hcx"
  }'

Fetch certificate in the API reference

• The sample body carries 1518@hcx in participantid. Replace it with the code you looked up in step 2, 1000003538@hcx for the dummy payer.
• <access token>: the same accessToken from step 1, in the same header.

You receive HTTP 200 with PEM text in encryption_cert. Some participants register a bare SubjectPublicKeyInfo (SPKI) public key rather than a full X.509 certificate. Import the value as an X.509 certificate first, and fall back to SPKI if that fails.

What you have now​

A token that every NHCX call accepts, a counterparty you know is on the network, and the key that seals its messages. Those are items 1, 4 and 5 of the base framework.

When it goes wrong​

Next steps​

• Your Certificate: make your own key pair, the counterpart of the one step 3 fetched.
• Creating and Updating a Participant: register your certificate and callback address.
• Building and Sending a JWE: seal a message with the certificate from step 3.