HCX Protocol
v0.9
v0.9
  • Summary*
  • Glossary*
  • Context
  • Introduction to HCX*
  • Technical Specifications
    • Open Protocol
      • Registries*
        • QR Code Specifications*
      • Claims Data Exchange (HCX) Protocol
        • Message Flows*
          • Primary Message Flow
          • Additional Message Flows
            • Redirect
            • Forward
            • Intra Cycle Communication*
              • Seeking Supporting Information
              • Seeking Beneficiary Consent
              • Seeking Account Information
            • Relay
            • Third party Information sharing
          • Notifications
            • Categories
            • List of key topics
        • Message Structure
        • API Specifications*
          • Registry APIs
          • Primary Flow APIs
          • Supporting APIs
          • Notification APIs
        • Error Handling
      • Data Security and Privacy
        • Transport Security
        • Message Security and Integrity
        • API Security*
      • Audit and Reporting
    • Digital Network Policies
  • Domain Specifications
    • Domain Data Models
      • Handling Attachments
      • Handling Processing Errors
    • Terminologies
    • Domain Specific Languages (DSLs)
    • FHIR Implementation Guide*
  • Business Policy Specifications
    • Access Control (Roles)*
    • Guidelines for Participant Onboarding*
      • Sandbox process
      • Production onboarding (Go live)*
      • Potential De-boarding scenarios
    • Guidelines for Grievance Redressal
      • Scope of disputes
      • Involved participants
      • Guideline process for dispute resolution
      • Guidelines for leveraging FTA
      • Next steps
    • Guidelines for SLAs and ecosystem satisfaction
    • Guidelines for Operating charges
    • Guidelines for Beneficiary Authentication by Providers/Payors
    • Guidelines for Event audits
    • Reference Templates
      • HCX - Terms of use
      • Payer-Provider addendum
      • Payer-Policyholder addendum
    • Next steps
  • Use cases*
    • OPD
      • Typical Workflows
        • Cashless
        • Reimbursement
      • Mapping to the HCX protocol
        • Cashless
        • Reimbursement
    • IPD
      • Typical Workflows
        • Cashless
        • Reimbursement
      • Mapping to the HCX protocol
        • Cashless
        • Reimbursement
    • Implementation Considerations
  • Contributing to the protocol
  • Future Focus Areas*
Powered by GitBook
On this page

Was this helpful?

Edit on GitHub
  1. Technical Specifications
  2. Open Protocol
  3. Claims Data Exchange (HCX) Protocol
  4. API Specifications*

Registry APIs

Details of the Registry APIs to access and manage registry entities

PreviousAPI Specifications*NextPrimary Flow APIs

Last updated 1 year ago

Was this helpful?

Participating Organisations/Systems Registry APIs

User Registry APIs

Following describes the participant organisations registry and the associated APIs. Same specification can be visualised in .

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

OpenAPI 3.0 document
Swagger Editor
OpenAPI 3.0 specification
link
get

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

Authorizations
Path parameters
user_idstringRequired

Unique identifier of the user/scheme on the HCX instance

Responses
200
OK
application/json
Responseall of
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
get
GET /user/read/{user_id} HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
{
  "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"
}
  • Participating Organisations/Systems Registry APIs
  • POST/participant/create
  • GET/participant/read/{participant_code}
  • POST/participant/search
  • POST/participant/update
  • POST/participant/delete
  • User Registry APIs
  • POST/user/create
  • GET/user/read/{user_id}
  • POST/user/search
  • POST/user/update
  • POST/user/delete
  • POST/participant/user/add
  • POST/participant/user/remove
get

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

Authorizations
Path parameters
participant_codestringRequired

Unique identifier of the participant/scheme on the HCX instance

Responses
200
OK
application/json
Responseall of
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
get
GET /participant/read/{participant_code} HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
{
  "participant_code": "pcpt01@HCX01",
  "linked_registry_codes": [
    "text"
  ],
  "participant_name": "text",
  "scheme_code": "default",
  "roles": "payer",
  "address": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "primaryEmail": "name@gmail.com",
  "additionalEmail": [
    "name@gmail.com"
  ],
  "phone": [
    "080 40004000"
  ],
  "primaryMobile": "9899912323",
  "additionalMobile": [
    "9100091000",
    "9899912323"
  ],
  "status": [
    "Created"
  ],
  "signing_cert_path": "text",
  "encryption_cert": "text",
  "endpoint_url": "https://example.com",
  "payment_details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
post

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.

Authorizations
Body
all ofOptional
Responses
200
OK
application/json
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /participant/create HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 486

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

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
}
  1. Filters to fetch the list of participants with role provider and payor.
{
  "filters": {
    "roles": { "or": ["provider","payor"] }
  }
}
  1. Filters to fetch the list of participants with participant name containing Hospital.
{
  "filters": {
    "participant_name": { "contains": "Hospital" }
  }
}
  1. Filters with nested fields, the below filter will return list of participants with the given ifsc code.
{
  "filters": {
    "payment_details.ifsc_code": { "eq": "BANK0001234" }
  }
}
Authorizations
Body
all ofOptional
Responses
200
OK
application/json
Responseall of
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /participant/search HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 76

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

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

Authorizations
Body
all ofOptional
Responses
200
OK
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /participant/update HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 520

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

No content

post

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

Authorizations
Body
all ofOptional
Responses
200
OK
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /participant/delete HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "participant_code": "pcpt01@HCX01"
}

No content

post

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.

Authorizations
Body
all ofOptional
Responses
200
OK
application/json
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /user/create HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 219

{
  "user_name": "User 01",
  "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"
}
{
  "timestamp": "1629057611000",
  "user_id": "user01@HCX01"
}
post

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" }
  }
}
  1. Filters to fetch the list of users with user name containing user01.
{
  "filters": {
    "user_name": { "contains": "user01" }
  }
}
  1. Filters with nested fields, the below filter will return list of users with the given role .
{
  "filters": {
    "tenant_roles.roles": { "eq": "admin" }
  }
}
Authorizations
Body
all ofOptional
Responses
200
OK
application/json
Responseall of
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /user/search HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "filters": {
    "user_id": {
      "eq": "user01@HCX01"
    }
  },
  "limit": 10,
  "offset": 0
}
{
  "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"
    }
  ]
}
post

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

Authorizations
Body
all ofOptional
Responses
200
OK
application/json
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /user/update HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "user_id": "user01@HCX01",
  "user_name": "user01",
  "pin": "text",
  "mobile": 8522812345,
  "email": "user01@domain_name.com",
  "linked_user_id": "text",
  "created_by": "Participant code / user Id"
}
{
  "timestamp": "1629057611000",
  "user_id": "user01@HCX01"
}
post

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

Authorizations
Body
all ofOptional
Responses
200
OK
application/json
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /user/delete HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 26

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

This API is to add users to a participant.

Authorizations
Body
all ofOptional
Responses
200
OK
application/json
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /participant/user/add HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "participant_code": "participant01@HCX01",
  "users": [
    {
      "user_id": "user01",
      "role": "viewer"
    },
    {
      "user_id": "user02",
      "role": "config-manager"
    }
  ]
}
{
  "timestamp": "1629057611000",
  "status": "SUCCESS"
}
post

This API is to remove users from a participant.

Authorizations
Body
all ofOptional
Responses
200
OK
application/json
400
Client Error
application/json
404
Resource not found
application/json
500
Downstream systems down/unhandled exceptions.
application/json
post
POST /participant/user/remove HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "participant_code": "participant01@HCX01",
  "users": [
    "“user01”",
    "“user02”"
  ]
}
{
  "timestamp": "1629057611000",
  "status": "SUCCESS"
}