openapi: 3.0.1
info:
  title: HCX Participant Registry APIs
  description: >-
    HCX participant registry acts as a source of truth for participant information on the platform. This registry stores key details about the participants on the exchange who can exchange data through it and exposes open APIs to manage & access the registry data.
  version: 1.0.0
tags:
  - name: Registry APIs
    description: HCX participant registry APIs
paths:

  /participant/create:
    post:
      tags:
        - Registry APIs
      description: 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.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ParticipantCreateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  participant_code:
                    type: string
                    description: Machine generated/readable unique identifier of the participant on the HCX instance.
                    example: "pcpt01@HCX01"

        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /participant/read/{participant_code}:
    get:
      parameters:
        - in: path
          name: participant_code
          required: true
          schema:
            type: string
          description: Unique identifier of the participant/scheme on the HCX instance   
      tags:
        - Registry APIs
      description: This API is to retrieve details of a single participant from the registry, using their participant code.
      security:
        - bearer_auth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ParticipantReadResponse'
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse' 
  /participant/search:
    post:
      tags:
        - Registry APIs
      description: |
        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" }
          }
        }
        ```


      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ParticipantSearchRequest'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseEnvelope'
                  - type: object
                    required:
                      - participants
                    properties:
                      participants:
                        type: array
                        description: List of participants matching with the input search criteria
                        items:
                          $ref: '#/components/schemas/ParticipantUpdateRequest'
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /participant/update:
    post:
      tags:
        - Registry APIs
      description: This API is to update a participant's information in the registry. participant_code must be mandatorily provided in the request.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ParticipantUpdateRequest'
      responses:
        '200':
          description: OK
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /participant/delete:
    post:
      tags:
        - Registry APIs
      description: This API is to delete a participant from the registry. API only does a soft delete of the participant.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - participant_code
                  properties:
                    participant_code:
                      type: string
                      description: Unique identifier of the participant on the HCX instance
                      example: "pcpt01@HCX01"

      responses:
        '200':
          description: OK
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:

    ParticipantCreateRequest:
      required:
        - participate_name
        - roles
        - mobile
        - status
        - encryption_cert
        - endpoint_url
      type: object
      properties:
        linked_registry_codes:
          type: array
          items:
            type: string
            pattern: '^.+@[a-z]+$'
          description: 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_name:
          type: string
          description: Human readable name for the participant
        scheme_code:
          type: string
          default: "default"
          description: 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:
          type: array
          items:
            type: string
            enum: ["provider", "payer", "agency.tpa", "agency.regulator", "research", "member.isnp", "agency.sponsor", "HIE/HIO.HCX"]
          example: payer
          description: Roles assigned to the participant as per the definition in the domain specifications. This will be used for access control.
        address:
          type: object
          description: Physical address of the facility including its geolocation
          additionalProperties: true
        primaryEmail:
          type: string
          format: email
          description: Primary email id for claims related communication.
        additionalEmail:
          type: array
          items:
            type: string
            format: email
          maxItems: 3
          description: Additional/alternative email ids of the participant. Maximum of 3 email addresses are allowed.
        phone:
          type: array
          items:
            type: string
          example: ["080 40004000"]
          maxItems: 3
          description: Landline numbers of the provider. Maximum of 3 landline numbers are allowed.
        primaryMobile:
          type: string
          example: "9899912323"
          description: Primary mobile number for claims related communication.
        additionalMobile:
          type: array
          items:
            type: string
          example: ["9100091000", "9899912323"]
          maxItems: 3
          description: Additional/alternate mobile numbers of the participant.
        status:
          type: array
          items:
            type: string
            enum:
              - Created
              - Active
              - InActive
              - Blocked
            default: Created
          description: Current status of the participant on the instance
        signing_cert_path:
          type: string
          description: uri/file path to signing certificate
        encryption_cert:
          type: string
          description: uri/file path to encryption certificate
        endpoint_url:
          type: string
          description: Default endpoint to make API calls
          format: uri
        payment_details:
          type: object
          description: Default payment details (UPI or A/C Number + IFSC Code)
          additionalProperties: true

    ParticipantSearchRequest:
      type: object
      additionalProperties: false
      properties:
        filters:
          type: object
          description: Filter conditions should be provider in filters.
          example: {"participant_code": { "eq": "pcpt01@HCX01" } }
        limit:
          type: number
          description: Size of the search result should return in the response.
          example: 10
        offset:
          type: number
          description: Offset is used to omit a specified number of rows before the beginning of the result set.
          example: 0

    ParticipantUpdateRequest:
      type: object
      required:
        - participant_code
      additionalProperties: false
      properties:
        participant_code:
          type: string
          description: Unique identifier of the participant/scheme on the HCX instance
          example: "pcpt01@HCX01"
        linked_registry_codes:
          type: array
          items:
            type: string
            pattern: '^.+@[a-z]+$'
          description: 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_name:
          type: string
          description: Human readable name for the participant
        scheme_code:
          type: string
          default: "default"
          description: 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:
          type: array
          items:
            type: string
            enum: ["provider", "payer", "agency.tpa", "agency.regulator", "research", "member.isnp", "agency.sponsor", "HIE/HIO.HCX"]
          example: payer
          description: Roles assigned to the participant as per the definition in the domain specifications. This will be used for access control.
        address:
          type: object
          description: Physical address of the facility including its geolocation
          additionalProperties: true
        primaryEmail:
          type: string
          format: email
          description: Primary email id for claims related communication.
        additionalEmail:
          type: array
          items:
            type: string
            format: email
          maxItems: 3
          description: Additional/alternative email ids of the participant. Maximum of 3 email addresses are allowed.
        phone:
          type: array
          items:
            type: string
          example: ["080 40004000"]
          maxItems: 3
          description: Landline numbers of the provider. Maximum of 3 landline numbers are allowed.
        primaryMobile:
          type: string
          example: "9899912323"
          description: Primary mobile number for claims related communication.
        additionalMobile:
          type: array
          items:
            type: string
          example: ["9100091000", "9899912323"]
          maxItems: 3
          description: Additional/alternate mobile numbers of the participant.
        status:
          type: array
          items:
            type: string
            enum:
              - Created
              - Active
              - InActive
              - Blocked
            default: Created
          description: Current status of the participant on the instance
        signing_cert_path:
          type: string
          description: uri/file path to signing certificate
        encryption_cert:
          type: string
          description: uri/file path to encryption certificate
        endpoint_url:
          type: string
          description: Default endpoint to make API calls
          format: uri
        payment_details:
          type: object
          description: Default payment details (UPI or A/C Number + IFSC Code)
          additionalProperties: true

    ParticipantReadResponse:
      type: object
      required:
        - participant_code
      additionalProperties: false
      properties:
        participant_code:
          type: string
          description: Unique identifier of the participant/scheme on the HCX instance
          example: "pcpt01@HCX01"
        linked_registry_codes:
          type: array
          items:
            type: string
            pattern: '^.+@[a-z]+$'
          description: 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_name:
          type: string
          description: Human readable name for the participant
        scheme_code:
          type: string
          default: "default"
          description: 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:
          type: array
          items:
            type: string
            enum: ["provider", "payer", "agency.tpa", "agency.regulator", "research", "member.isnp", "agency.sponsor", "HIE/HIO.HCX"]
          example: payer
          description: Roles assigned to the participant as per the definition in the domain specifications. This will be used for access control.
        address:
          type: object
          description: Physical address of the facility including its geolocation
          additionalProperties: true
        primaryEmail:
          type: string
          format: email
          description: Primary email id for claims related communication.
        additionalEmail:
          type: array
          items:
            type: string
            format: email
          maxItems: 3
          description: Additional/alternative email ids of the participant. Maximum of 3 email addresses are allowed.
        phone:
          type: array
          items:
            type: string
          example: ["080 40004000"]
          maxItems: 3
          description: Landline numbers of the provider. Maximum of 3 landline numbers are allowed.
        primaryMobile:
          type: string
          example: "9899912323"
          description: Primary mobile number for claims related communication.
        additionalMobile:
          type: array
          items:
            type: string
          example: ["9100091000", "9899912323"]
          maxItems: 3
          description: Additional/alternate mobile numbers of the participant.
        status:
          type: array
          items:
            type: string
            enum:
              - Created
              - Active
              - InActive
              - Blocked
            default: Created
          description: Current status of the participant on the instance
        signing_cert_path:
          type: string
          description: uri/file path to signing certificate
        encryption_cert:
          type: string
          description: uri/file path to encryption certificate
        endpoint_url:
          type: string
          description: Default endpoint to make API calls
          format: uri
        payment_details:
          type: object
          description: Default payment details (UPI or A/C Number + IFSC Code)
          additionalProperties: true

    ResponseEnvelope:
      required:
        - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: Unix timestamp when the request is sent
          example: "1629057611000"

    ErrorResponse:
      required:
        - error
        - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: Unix timestamp when the response is sent.
          example: "1629057611000"
        error:
          $ref: '#/components/schemas/Error'
      description: This is a response to the ClaimForm API call
    Error:
      type: object
      properties:
        code:
          type: string
          description: error code from the system - expected to be namespaced for better readability
        message:
          type: string
          description: Short description of the error
        trace:
          type: string
          description: Long description supporting the Code

  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT