Skip to main content

Submit the participant update (v1)

Sandbox call. Updates a participant's registry record; participant_code and roles are mandatory, every other field (certificate, endpoint, contacts, status) is optional.

POST/participant/update

Business purpose

Participant details change over the life of an integration: callback endpoints move, encryption certificates are rotated annually, contact numbers and payment details change. The registry is the source of truth that the gateway routes from, so those changes must land there, not just in the participant's own configuration. This v1 update lets an organisation amend any attribute of its full record in one synchronous call, and the sandbox onboarding document names it as the way to update the bridge URL, the encryption certificate or any other attribute.

When to use

Use it in the sandbox, after registration, whenever a detail of your participant record must change. The sandbox address is https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/update. In production, use /v2/participant/update followed by /update/validate to change the certificate or the callback URL. For a certificate change alone, /v2/update/cert is simpler.

Preconditions

  • The participant already exists and you know its participant_code.
  • You have a valid access token in the bearer_auth header.
  • If you change the certificate, the new private key is already on your callback server.

Postconditions

The registry record now holds the new values. Other participants see the change on their next lookup, though some may cache your certificate for up to 24 hours.

Common mistakes

  • Leaving out roles: it is required even when roles do not change.
  • Using the v2 field names in this body.
  • Publishing a new certificate before its private key is live, so callbacks cannot be decrypted.
  • Setting a callback URL with an IP address or port.

Best practices

  • Read the current record with /participant/search first and send the full intended state, so a partial body does not unintentionally blank optional fields.
  • Rotate certificates in two phases and keep the old private key for at least 24 hours, the documented certificate cache TTL.
  • Confirm callback reachability (domain name, India-based host, NAT IPs 3.109.99.210, 13.126.152.0 and 13.200.129.223 whitelisted) before pointing endpoint_URL at a new host.
  • Log the change with who requested it; registry changes affect where encrypted health data is delivered.

Related scenario

A hospital migrates its claims callback service to a new domain. Before touching the registry the team deploys the service, verifies the NHCX NAT IPs are whitelisted and copies the existing PKCS8 private key across. They fetch a Bearer token via /get/session, read the current record with /participant/search, and call /participant/update with participant_code, roles and the new endpoint_URL. The registry returns 200. The next /v1/preauth/on_submit callback from the payer arrives at the new domain and is acknowledged with 202 within 30 seconds.

Specification

Chapter Your certificate of the NHCX integration specification.

Authorizations

bearer_authapiKeyRequired

Every NHCX call carries the access token from the session call in a header named bearer_auth, as the word Bearer, a space and the token. NHCX reads bearer_auth, not Authorization.

Example Bearer <access token>

Headers

AcceptstringRequired

Always application/json on the participant service.

Body

participant_codestring
participant_namestring
scheme_codestring
rolesstring[]
primaryEmailstring
phonestring[]
primaryMobilestring
endpoint_urlstring
signing_cert_pathstring
encryption_certstring

Responses

200

HTTP 200 with a string body (the OpenAPI declares string; the sandbox onboarding document shows the participant code echoed back, for example 100001@sbx).

_contentTypestring
_bodystring