Participant registry
The participant service holds the registry: who is on the exchange, their certificates and callback addresses, and the policies linked to a beneficiary.
Two things to know before you call
/get/session is not the gateway sessions call. The participant service publishes its own token call under the same name other documents use for the ABDM gateway session. The two differ in address, headers, body encoding and response field names. Use the gateway call by default. The differences are set out in Session token.
APIs
The rows run in the order the calls happen: your token and your own record, then the payer's products and policy links, then the lookups a provider makes before it sends a message. Environment is Sandbox or Production when a call belongs to one environment. Both means no environment limit is published, so the path goes after either base.
| Call | Called by | Environment | Method and path | What it does |
|---|---|---|---|---|
| Get session token | Any participant | Both | POST /get/session | Exchanges the participant's client_id and client_secret (OAuth 2.0 client credentials) for a Bearer access_token valid for 1200 seconds. |
| Participant update (v1) | Any participant | Sandbox | POST /participant/update | Updates a participant's registry record; participant_code and roles are mandatory, every other field (certificate, endpoint, contacts, status) is optional. |
| Participant certificate and bridge update (v2) | Any participant | Production | POST /v2/participant/update | Stages a change to a participant encryption certificate and/or endpoint URL; returns a transactionid for passcode confirmation via /update/validate. |
| Update certificate (v2, no passcode) | Any participant | Both | POST /v2/update/cert | Replaces a participant's public encryption certificate by participantId without passcode validation; the same schema is echoed back on success. |
| Link payer product | Payer | Both | POST /product/link | Registers a product (product id and name) against a payer's participant code, so that it can be referenced in ABHA policy links. |
| De-link payer product | Payer | Both | POST /product/delink | Removes a product (product id and name) from a payer's participant code in the registry. |
| Get product owner | Payer, to confirm its products; a provider, to find a product's payer | Both | POST /product/getowner | Resolves a product id to the participant code of the payer that owns it. |
| Get product id and name | Not stated | Both | POST /participant/getProductIdName | Retrieving API described as generating the product id and product name; declared with a bare string request body and a participant-code response. |
| Link ABHA number to policies | Payer | Both | POST /participant/link/abha/policy | Payer-side write that links a beneficiary's ABHA number and member id to one or more products, so provider policy lookups can find them. |
| Link ABHA number to policies (v2) | Payer | Both | POST /v2/participant/link/abha/policy | v2 variant of the ABHA policy link; same ParticipantLinkAbhaRequest body and ParticipantLinkAbhaResponse as the unversioned call. |
| Initiate ABHA policy link (v2) | Payer | Both | POST /v2/participant/link/abha/policy/init | First half of the two-step v2 link: submits the ABHA policy link request, to be confirmed with a passcode via the validate endpoint. |
| Validate ABHA policy link (v2) | Payer | Both | GET /v2/participant/link/abha/policy/validate | Second half of the two-step v2 link: confirms an initiated ABHA policy link with the passcode and transactionId query parameters. |
| De-link ABHA policies | Payer | Both | POST /participant/delink/abha/policy | Removes specific products from a member's policy link for a payer, keyed on payerid, memberid and the products listed. |
| De-link ABHA policies (v2) | Payer | Both | POST /v2/participant/delink/abha/policy | v2 variant of the ABHA policy de-link; same ParticipantDeLinkAbhaRequest body and response as the unversioned call. |
| Fetch participants list | Any participant | Both | POST /fetch/participants/list | Payer discovery: lists participants filtered by role, registration date window and optional entity type; the first step of the cashless workflow. |
| Participant search | Any participant | Both | POST /participant/search | Reads a participant's full registry record by participant_code, including roles, status, encryption_cert and endpoint_url. |
| Participant details (v2 search) | Any participant | Both | POST /participant/details | v2 variant of participant search: takes participant_code and returns the matching full registry records. |
| Get beneficiary policies | Provider | Both | POST /participant/get/policies | Looks up the policies linked to a beneficiary by ABHA number, member id or mobile number, returning the payer and product details needed for claims. |
| Get beneficiary policies (v2) | Provider | Both | POST /v2/participant/get/policies | v2 variant of the beneficiary policy lookup; same FetchParticipantPoliciesRequest body and ParticipantListResponse as the unversioned call. |
| Fetch certificate | Any participant, before it seals a message | Both | POST /fetch/certs | Returns a participant's public encryption certificate (PEM X.509 or SPKI key) by participantid; cache it for 24 hours and use it to build the JWE. |
| Fetch certificate path | Any participant | Both | POST /fetch/certs/path | Companion to /fetch/certs: takes the same participantid body and returns a string described as the participant's certificate path. |
Base URLs
| Environment | Base URL |
|---|---|
| Sandbox, Participant service. | https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice |
| Production. | https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice |
Guides that use these calls
- Creating and updating a participant
- Finding participants and policies
- Fetching a recipient certificate
- Get your sandbox credentials
- Quickstart
- The recipient cannot decrypt your message
The whole specification, with a request you can send from the page, is the Participant registry API reference.