Registry APIs

Details of the Registry APIs to access and manage registry entities

Participating Organisations/Systems Registry APIs

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

Authorization

bearer_auth

Body

application/json

linked_registry_codesarray of string

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.

participant_namestring

Human readable name for the participant

scheme_codestring

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”.

roles*array of enum

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

Example: "payer"

addressobject

Physical address of the facility including its geolocation

primaryEmailstring (email)

Primary email id for claims related communication.

additionalEmailarray of string (email)

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

phonearray of string

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

primaryMobilestring

Primary mobile number for claims related communication.

Example: "9899912323"

additionalMobilearray of string

Additional/alternate mobile numbers of the participant.

status*array of enum

Current status of the participant on the instance

signing_cert_pathstring

uri/file path to signing certificate

encryption_cert*string

uri/file path to encryption certificate

endpoint_url*string (uri)

Default endpoint to make API calls

payment_detailsobject

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

Response

200400404500

OK

Body

application/json

participant_codestring

Machine generated/readable unique identifier of the participant on the HCX instance.

Example: "pcpt01@HCX01"

Request

JavaScriptCurlPython

const response = await fetch('/participant/create', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "roles": "payer",
      "status": [
        "Created"
      ],
      "encryption_cert": "text",
      "endpoint_url": "https://example.com"
    }),
});
const data = await response.json();

Response

200400404500

{
  "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}

Authorization

bearer_auth

Path parameters

participant_code*string

Unique identifier of the participant/scheme on the HCX instance

Response

200400404500

OK

Body

application/json

participant_code*string

Unique identifier of the participant/scheme on the HCX instance

Example: "pcpt01@HCX01"

linked_registry_codesarray of string

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.

participant_namestring

Human readable name for the participant

scheme_codestring

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”.

rolesarray of enum

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

Example: "payer"

addressobject

Physical address of the facility including its geolocation

primaryEmailstring (email)

Primary email id for claims related communication.

additionalEmailarray of string (email)

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

phonearray of string

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

primaryMobilestring

Primary mobile number for claims related communication.

Example: "9899912323"

additionalMobilearray of string

Additional/alternate mobile numbers of the participant.

statusarray of enum

Current status of the participant on the instance

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)

Request

JavaScriptCurlPython

const response = await fetch('/participant/read/{participant_code}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200400404500

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

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.

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:

1. 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
}

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

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

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

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

4. 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

Authorization

bearer_auth

Body

application/json

filtersobject

Filter conditions should be provider in filters.

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

Response

200400404500

OK

Body

application/json

timestamp*string

Unix timestamp when the request is sent

Example: "1629057611000"

participants*array of ParticipantUpdateRequest (object)

List of participants matching with the input search criteria

Request

JavaScriptCurlPython

const response = await fetch('/participant/search', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400404500

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

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

POST/participant/update

Authorization

bearer_auth

Body

application/json

participant_code*string

Unique identifier of the participant/scheme on the HCX instance

Example: "pcpt01@HCX01"

linked_registry_codesarray of string

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.

participant_namestring

Human readable name for the participant

scheme_codestring

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”.

rolesarray of enum

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

Example: "payer"

addressobject

Physical address of the facility including its geolocation

primaryEmailstring (email)

Primary email id for claims related communication.

additionalEmailarray of string (email)

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

phonearray of string

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

primaryMobilestring

Primary mobile number for claims related communication.

Example: "9899912323"

additionalMobilearray of string

Additional/alternate mobile numbers of the participant.

statusarray of enum

Current status of the participant on the instance

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)

Response

200400404500

OK

Request

JavaScriptCurlPython

const response = await fetch('/participant/update', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "participant_code": "pcpt01@HCX01"
    }),
});
const data = await response.json();

Response

400404500

{
  "timestamp": "1629057611000",
  "error": {
    "code": "text",
    "message": "text",
    "trace": "text"
  }
}

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

POST/participant/delete

Authorization

bearer_auth

Body

application/json

participant_code*string

Unique identifier of the participant on the HCX instance

Example: "pcpt01@HCX01"

Response

200400404500

OK

Request

JavaScriptCurlPython

const response = await fetch('/participant/delete', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "participant_code": "pcpt01@HCX01"
    }),
});
const data = await response.json();

Response

400404500

{
  "timestamp": "1629057611000",
  "error": {
    "code": "text",
    "message": "text",
    "trace": "text"
  }
}

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

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

Authorization

bearer_auth

Body

application/json

user_name*string

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

tenant_rolesarray of object

Base tenant of the admin user

created_by*string

participant_code or user_id of the created_by user

Example: "Participant code / user Id"

Response

200400404500

OK

Body

application/json

timestampstring

Unix timestamp when the request is sent

Example: "1629057611000"

user_idstring

Machine generated/readable unique identifier of the user on the HCX instance.

Example: "user01@HCX01"

Request

JavaScriptCurlPython

const response = await fetch('/user/create', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "user_name": "User 01",
      "created_by": "Participant code / user Id"
    }),
});
const data = await response.json();

Response

200400404500

{
  "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}

Authorization

bearer_auth

Path parameters

user_id*string

Unique identifier of the user/scheme on the HCX instance

Response

200400404500

OK

Body

application/json

user_id*string

Unique identifier of the user/scheme on the HCX instance

Example: "user01@HCX01"

user_namestring

Human readable name for the user

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

tenant_rolesarray of object

Base tenant of the admin user

created_bystring

participant_code or user id of the created user

Example: "Participant code / user Id"

Request

JavaScriptCurlPython

const response = await fetch('/user/read/{user_id}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200400404500

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

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:

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

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

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

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

3. 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

Authorization

bearer_auth

Body

application/json

filtersobject

Filter conditions should be provider in filters.

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

Response

200400404500

OK

Body

application/json

timestamp*string

Unix timestamp when the request is sent

Example: "1629057611000"

users*array of UserReadResponse (object)

List of users matching with the input search criteria

Request

JavaScriptCurlPython

const response = await fetch('/user/search', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400404500

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

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

POST/user/update

Authorization

bearer_auth

Body

application/json

user_id*string

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"

Response

200400404500

OK

Body

application/json

timestampstring

Unix timestamp when the request is sent

Example: "1629057611000"

user_idstring

Machine generated/readable unique identifier of the user on the HCX instance.

Example: "user01@HCX01"

Request

JavaScriptCurlPython

const response = await fetch('/user/update', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "user_id": "user01@HCX01"
    }),
});
const data = await response.json();

Response

200400404500

{
  "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

Authorization

bearer_auth

Body

application/json

user_id*string

Unique identifier of the user on the HCX instance

Example: "user01@HCX01"

Response

200400404500

OK

Body

application/json

timestampstring

Unix timestamp when the request is sent

Example: "1629057611000"

user_idstring

Machine generated/readable unique identifier of the user on the HCX instance.

Example: "user01@HCX01"

statusstring

status of the user in the registry

Example: "Inactive"

Request

JavaScriptCurlPython

const response = await fetch('/user/delete', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "user_id": "user01@HCX01"
    }),
});
const data = await response.json();

Response

200400404500

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

This API is to add users to a participant.

POST/participant/user/add

Authorization

bearer_auth

Body

application/json

participant_code*string

Unique identifier of the participant on the HCX instance

Example: "participant01@HCX01"

users*array of object

List of the users to be added to a participant.

Response

200400404500

OK

Body

application/json

timestampstring

Unix timestamp when the request is sent

Example: "1629057611000"

statusstring

Status of the API.

Example: "SUCCESS"

Request

JavaScriptCurlPython

const response = await fetch('/participant/user/add', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "participant_code": "participant01@HCX01",
      "users": [
        {
          "user_id": "user01",
          "role": "viewer"
        },
        {
          "user_id": "user02",
          "role": "config-manager"
        }
      ]
    }),
});
const data = await response.json();

Response

200400404500

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

This API is to remove users from a participant.

POST/participant/user/remove

Authorization

bearer_auth

Body

application/json

participant_code*string

Unique identifier of the participant on the HCX instance

Example: "participant01@HCX01"

users*array of object

List of users to be removed from a participant.

Response

200400404500

OK

Body

application/json

timestampstring

Unix timestamp when the request is sent

Example: "1629057611000"

statusstring

Status of the API.

Example: "SUCCESS"

Request

JavaScriptCurlPython

const response = await fetch('/participant/user/remove', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "participant_code": "participant01@HCX01",
      "users": [
        "“user01”",
        "“user02”"
      ]
    }),
});
const data = await response.json();

Response

200400404500

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

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