Registry APIs

Details of the Registry APIs to access and manage registry entities

Participating Organisations/Systems Registry APIs

Following OpenAPI 3.0 document describes the participant organisations registry and the associated APIs. Same specification can be visualised in Swagger Editor.

User Registry APIs

Following OpenAPI 3.0 specification details these APIs in detail. These API specs can be opened in swagger editor via this link.

PreviousAPI Specifications*NextPrimary Flow APIs

Last updated 1 year ago

Was this helpful?

This API is to create a user in the registry. API generates a unique user id and returns the id in the response on successfull creation of user.

post

/user/create

Authorizations

Body

user_namestringrequired

Human readable user name

Example: User 01

pinstring

Identification pin if needed to be set

mobilestring

Mobile number of the user

Example: 8522812345

emailstring · email

Email Id of the user

Example: user01@domain_name.com

linked_user_idstring

User ID in the source system

created_bystringrequired

participant_code or user_id of the created_by user

Example: Participant code / user Id

tenant_rolesobject[]

Base tenant of the admin user

Example: [{"participant_code":"pcpt@hcx","role":"admin"}]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/user/create' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"user_name":"User 01","mobile":8522812345,"email":"user01@domain_name.com","created_by":"Participant code / user Id","tenant_roles":[{"participant_code":"pcpt@hcx","role":"admin"}]}'

200

400

404

500

{
  "timestamp": "1629057611000",
  "user_id": "user01@HCX01"
}

This API is to retrieve details of a single user from the registry, using their user id .

get

/user/read/{user_id}

Authorizations

Path parameters

user_idstringrequired

Unique identifier of the user/scheme on the HCX instance

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url '/user/read/{user_id}' \
  --header 'Authorization: Bearer JWT'

200

400

404

500

{
  "user_id": "user01@HCX01",
  "user_name": "text",
  "pin": "text",
  "mobile": 8522812345,
  "email": "user01@domain_name.com",
  "linked_user_id": "text",
  "created_by": "Participant code / user Id",
  "tenant_roles": [
    {
      "participant_code": "pcpt@hcx",
      "role": "admin"
    }
  ]
}

This API is to search for users in the registry. API returns list of users matching the input criteria.

Search filter supports all the fields. If multiple filter conditions are provided, they are processed by applying AND operation.

Limit and Offset are optional fields. The limit option allows you to limit the number of rows should be returned in the response, while offset allows you to omit a specified number of rows before the beginning of the result set.

Following are the operations supported by search filter:

contains("contains")
eq("=")
neq("!=")
between("range")
or("or")
startsWith("startsWith")
endsWith("endsWith")
notContains("notContains")
notStartsWith("notStartsWith")
notEndsWith("notEndsWith")
queryString("queryString")
gt(">")
lt("<")
gte(">=")
lte("<=")

Following are few example of search filter usage:

Filters to fetch the list of users with user_id user01@hcx Search response will return the user details.

{
  "filters": {
    "user_id": { "eq": "user01" }
  }
}

Filters to fetch the list of users with user name containing user01.

{
  "filters": {
    "user_name": { "contains": "user01" }
  }
}

Filters with nested fields, the below filter will return list of users with the given role .

{
  "filters": {
    "tenant_roles.roles": { "eq": "admin" }
  }
}

post

/user/search

Authorizations

Body

limitnumber

Size of the search result should return in the response.

Example: 10

offsetnumber

Offset is used to omit a specified number of rows before the beginning of the result set.

Example: 0

filtersobject

Filter conditions should be provider in filters.

Example: {"user_id":{"eq":"user01@HCX01"}}

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/user/search' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"limit":10,"offset":0,"filters":{"user_id":{"eq":"user01@HCX01"}}}'

200

400

404

500

{
  "timestamp": "1629057611000",
  "users": [
    {
      "user_id": "user01@HCX01",
      "user_name": "text",
      "pin": "text",
      "mobile": 8522812345,
      "email": "user01@domain_name.com",
      "linked_user_id": "text",
      "created_by": "Participant code / user Id",
      "tenant_roles": [
        {
          "participant_code": "pcpt@hcx",
          "role": "admin"
        }
      ]
    }
  ]
}

This API is to update a user's information in the registry. user_id must be mandatorily provided in the request.

post

/user/update

Authorizations

Body

user_idstringrequired

Unique identifier of the user/scheme on the HCX instance

Example: user01@HCX01

user_namestring

Human readable name for the user

Example: user01

pinstring

Identification pin if needed to be set

mobilestring

Mobile number of the user

Example: 8522812345

emailstring · email

Email Id of the user

Example: user01@domain_name.com

linked_user_idstring

User ID in the source system

created_bystring

participant_code or user id of the created user

Example: Participant code / user Id

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/user/update' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"user_id":"user01@HCX01","user_name":"user01","mobile":8522812345,"email":"user01@domain_name.com","created_by":"Participant code / user Id"}'

200

400

404

500

{
  "timestamp": "1629057611000",
  "user_id": "user01@HCX01"
}

This API is to delete a user from the registry. API only does a soft delete of the user.

post

/user/delete

Authorizations

Body

user_idstringrequired

Unique identifier of the user on the HCX instance

Example: user01@HCX01

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/user/delete' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"user_id":"user01@HCX01"}'

200

400

404

500

{
  "timestamp": "1629057611000",
  "user_id": "user01@HCX01",
  "status": "Inactive"
}

This API is to add users to a participant.

post

/participant/user/add

Authorizations

Body

participant_codestringrequired

Unique identifier of the participant on the HCX instance

Example: participant01@HCX01

usersobject[]required

List of the users to be added to a participant.

Example: [{"user_id":"user01","role":"viewer"},{"user_id":"user02","role":"config-manager"}]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/participant/user/add' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"participant_code":"participant01@HCX01","users":[{"user_id":"user01","role":"viewer"},{"user_id":"user02","role":"config-manager"}]}'

200

400

404

500

{
  "timestamp": "1629057611000",
  "status": "SUCCESS"
}

This API is to remove users from a participant.

post

/participant/user/remove

Authorizations

Body

participant_codestringrequired

Unique identifier of the participant on the HCX instance

Example: participant01@HCX01

usersobject[]required

List of users to be removed from a participant.

Example: ["“user01”","“user02”"]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/participant/user/remove' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"participant_code":"participant01@HCX01","users":["“user01”","“user02”"]}'

200

400

404

500

{
  "timestamp": "1629057611000",
  "status": "SUCCESS"
}

This API is to create a participant in the registry. API generates a unique participant code and returns the code in the response on successfule creation of participant.

post

/participant/create

Authorizations

Body

participant_namestring

Human readable name for the participant

scheme_codestring · default: default

name/code of the scheme provided by the payor. scheme_code is mandatory for all participants with role “payer”. If the payer wishes to use a single entry for all its schemes, the scheme_code value should be set to “default”.

addressobject

Physical address of the facility including its geolocation

primaryEmailstring · email

Primary email id for claims related communication.

primaryMobilestring

Primary mobile number for claims related communication.

Example: 9899912323

signing_cert_pathstring

uri/file path to signing certificate

encryption_certstringrequired

uri/file path to encryption certificate

endpoint_urlstring · urirequired

Default endpoint to make API calls

payment_detailsobject

Default payment details (UPI or A/C Number + IFSC Code)

linked_registry_codesstring[]

Identifier of the participant in other registries. Each identifier shall be in a “normalised” notation having the structure “identifier@registry”, where registry is a unique code for the registry system and identifier is the unique id of the participant in that registry system. e.g. - facility001@hfr, to link the provider record to HFR record. The list of supported registry codes (e.g. hfr, rohini, etc) should be a configuration at the HCX instance level.

additionalEmailstring · email[]

Additional/alternative email ids of the participant. Maximum of 3 email addresses are allowed.

phonestring[]

Landline numbers of the provider. Maximum of 3 landline numbers are allowed.

Example: ["080 40004000"]

additionalMobilestring[]

Additional/alternate mobile numbers of the participant.

Example: ["9100091000","9899912323"]

rolesstring · enum[]required

Roles assigned to the participant as per the definition in the domain specifications. This will be used for access control.

Example: payer

statusstring · enum · default: Created[]required

Current status of the participant on the instance

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/participant/create' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"scheme_code":"default","address":{"ANY_ADDITIONAL_PROPERTY":"anything"},"primaryMobile":"9899912323","encryption_cert":"text","endpoint_url":"https://example.com","payment_details":{"ANY_ADDITIONAL_PROPERTY":"anything"},"linked_registry_codes":[null],"additionalEmail":[null],"phone":["080 40004000"],"additionalMobile":["9100091000","9899912323"],"roles":"payer","status":["Created"]}'

200

400

404

500

{
  "participant_code": "pcpt01@HCX01"
}

This API is to retrieve details of a single participant from the registry, using their participant code.

get

/participant/read/{participant_code}

Authorizations

Path parameters

participant_codestringrequired

Unique identifier of the participant/scheme on the HCX instance

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url '/participant/read/{participant_code}' \
  --header 'Authorization: Bearer JWT'

200

400

404

500

{
  "participant_code": "pcpt01@HCX01",
  "participant_name": "text",
  "scheme_code": "default",
  "address": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "primaryEmail": "hello@example.com",
  "primaryMobile": "9899912323",
  "signing_cert_path": "text",
  "encryption_cert": "text",
  "endpoint_url": "https://example.com",
  "payment_details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "linked_registry_codes": [
    "text"
  ],
  "additionalEmail": [
    "hello@example.com"
  ],
  "phone": [
    "080 40004000"
  ],
  "additionalMobile": [
    "9100091000",
    "9899912323"
  ],
  "roles": "payer",
  "status": [
    "Created"
  ]
}

This API is to search for participants in the registry. API returns list of participants matching the input criteria.

Search filter supports all the fields. If multiple filter conditions are provided, they are processed by applying AND operation.

Following are the operations supported by search filter:

contains("contains")
eq("=")
neq("!=")
between("range")
or("or")
startsWith("startsWith")
endsWith("endsWith")
notContains("notContains")
notStartsWith("notStartsWith")
notEndsWith("notEndsWith")
queryString("queryString")
gt(">")
lt("<")
gte(">=")
lte("<=")

Following are few example of search filter usage:

Filters to fetch the list of participants with role provider and status is Created. Search response will return only 10 participants as the limit is 10.

{
  "filters": {
    "roles": { "eq": "provider" },
    "status": { "eq": "Created" }
  },
  "limit": 10,
  "offset": 0
}

Filters to fetch the list of participants with role provider and payor.

{
  "filters": {
    "roles": { "or": ["provider","payor"] }
  }
}

Filters to fetch the list of participants with participant name containing Hospital.

{
  "filters": {
    "participant_name": { "contains": "Hospital" }
  }
}

Filters with nested fields, the below filter will return list of participants with the given ifsc code.

{
  "filters": {
    "payment_details.ifsc_code": { "eq": "BANK0001234" }
  }
}

post

/participant/search

Authorizations

Body

limitnumber

Size of the search result should return in the response.

Example: 10

offsetnumber

Offset is used to omit a specified number of rows before the beginning of the result set.

Example: 0

filtersobject

Filter conditions should be provider in filters.

Example: {"participant_code":{"eq":"pcpt01@HCX01"}}

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/participant/search' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"limit":10,"offset":0,"filters":{"participant_code":{"eq":"pcpt01@HCX01"}}}'

200

400

404

500

{
  "timestamp": "1629057611000",
  "participants": [
    {
      "participant_code": "pcpt01@HCX01",
      "participant_name": "text",
      "scheme_code": "default",
      "address": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "primaryEmail": "hello@example.com",
      "primaryMobile": "9899912323",
      "signing_cert_path": "text",
      "encryption_cert": "text",
      "endpoint_url": "https://example.com",
      "payment_details": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "linked_registry_codes": [
        "text"
      ],
      "additionalEmail": [
        "hello@example.com"
      ],
      "phone": [
        "080 40004000"
      ],
      "additionalMobile": [
        "9100091000",
        "9899912323"
      ],
      "roles": "payer",
      "status": [
        "Created"
      ]
    }
  ]
}

This API is to update a participant's information in the registry. participant_code must be mandatorily provided in the request.

post

/participant/update

Authorizations

Body

participant_codestringrequired

Unique identifier of the participant/scheme on the HCX instance

Example: pcpt01@HCX01

participant_namestring

Human readable name for the participant

scheme_codestring · default: default

addressobject

Physical address of the facility including its geolocation

primaryEmailstring · email

Primary email id for claims related communication.

primaryMobilestring

Primary mobile number for claims related communication.

Example: 9899912323

signing_cert_pathstring

uri/file path to signing certificate

encryption_certstring

uri/file path to encryption certificate

endpoint_urlstring · uri

Default endpoint to make API calls

payment_detailsobject

Default payment details (UPI or A/C Number + IFSC Code)

linked_registry_codesstring[]

additionalEmailstring · email[]

Additional/alternative email ids of the participant. Maximum of 3 email addresses are allowed.

phonestring[]

Landline numbers of the provider. Maximum of 3 landline numbers are allowed.

Example: ["080 40004000"]

additionalMobilestring[]

Additional/alternate mobile numbers of the participant.

Example: ["9100091000","9899912323"]

rolesstring · enum[]

Roles assigned to the participant as per the definition in the domain specifications. This will be used for access control.

Example: payer

statusstring · enum · default: Created[]

Current status of the participant on the instance

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/participant/update' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"participant_code":"pcpt01@HCX01","scheme_code":"default","address":{"ANY_ADDITIONAL_PROPERTY":"anything"},"primaryMobile":"9899912323","payment_details":{"ANY_ADDITIONAL_PROPERTY":"anything"},"linked_registry_codes":[null],"additionalEmail":[null],"phone":["080 40004000"],"additionalMobile":["9100091000","9899912323"],"roles":"payer","status":["Created"]}'

200

400

404

500

No body

This API is to delete a participant from the registry. API only does a soft delete of the participant.

post

/participant/delete

Authorizations

Body

participant_codestringrequired

Unique identifier of the participant on the HCX instance

Example: pcpt01@HCX01

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/participant/delete' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"participant_code":"pcpt01@HCX01"}'

200

400

404

500

No body