AlayaCare referral inbox API

openapi: 3.2.0
info:
  title: Alayacare referral inbox API
  version: '1.0'
servers:
- url: https://api.{env}.alayamarket.{region}/offers
  variables:
    env:
      description: The server environment.
      enum:
      - staging
      - sandbox
      - prod
      default: prod
    region:
      description: The server top-level domain indicating the region.
      enum:
      - ca
      - com
      - com.au
      default: ca
security:
- CognitoAuthorizer: []
tags:
- name: referral inbox
paths:
  /v1/inbox/referrals:
    get:
      tags:
      - referral inbox
      description: '# Authorization

        Required role: `org_admin`


        # Description

        Get a collection of Referrals matched to the Supply Organization.

        '
      parameters:
      - in: query
        name: referral_status
        schema:
          $ref: '#/components/schemas/ReferralStatusCore'
      - in: query
        name: sequence_id
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/OfferIdQueryParam'
      - $ref: '#/components/parameters/ShiftIdQueryParam'
      - $ref: '#/components/parameters/RevisionsQueryParam'
      - $ref: '#/components/parameters/PageNumberParam'
      - $ref: '#/components/parameters/ItemsPerPageParam'
      - $ref: '#/components/parameters/SortByParam'
      - $ref: '#/components/parameters/SortOrderParam'
      responses:
        200:
          description: Successfully returned Referral Inbox Collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxReferralPageResponse'
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${OfferApiFunctionV2.Arn}:live/invocations
        httpMethod: POST
        passthroughBehavior: when_no_match
        type: aws_proxy
  /v1/inbox/referrals/{referral_id}:
    parameters:
    - $ref: '#/components/parameters/ReferralIdPathParam'
    get:
      tags:
      - referral inbox
      description: '# Authorization

        Required role: `org_admin`


        # Description

        Get the anonymized details of Referrals matched to the Supply

        organization. This must contain no PHI.

        '
      responses:
        200:
          description: Successfully returned Referral Inbox Scalar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxReferralDetailResponse'
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${OfferApiFunctionV2.Arn}:live/invocations
        httpMethod: POST
        passthroughBehavior: when_no_match
        type: aws_proxy
  /v1/inbox/referrals/{referral_id}/mark_processed:
    parameters:
    - $ref: '#/components/parameters/ReferralIdPathParam'
    post:
      tags:
      - referral inbox
      description: '# Authorization

        Required role: `org_admin`


        Required referral state: `assigned`


        # Description

        Acknowledges that the Supply organization has received and processed the assigned Referral.

        This will mark the Referral as `processed` and will inform the Demand organization.

        '
      responses:
        204:
          description: Successfully marked Referral as Processed.
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${OfferApiFunctionV2.Arn}:live/invocations
        httpMethod: POST
        passthroughBehavior: when_no_match
        type: aws_proxy
  /v1/inbox/referrals/{referral_id}/cancel:
    parameters:
    - $ref: '#/components/parameters/ReferralIdPathParam'
    post:
      tags:
      - referral inbox
      description: "# Authorization\nRequired role: `org_admin`\n\n# Description\nCancel an Referral after it's assigned to the Supply Organization.  \nA Referral can only be Cancelled if the status is `assigned` or `processed`.\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxReferralCancelRequest'
      responses:
        204:
          description: Successfully marked Referral as Cancelled
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${OfferApiFunctionV2.Arn}:live/invocations
        httpMethod: POST
        passthroughBehavior: when_no_match
        type: aws_proxy
  /v1/inbox/referrals/{referral_id}/tasks/update:
    parameters:
    - $ref: '#/components/parameters/ReferralIdPathParam'
    post:
      tags:
      - referral inbox
      description: '# Authorization

        Required role: `org_admin`


        # Description

        Update referral tasks for a given referral.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxClientTasksUpdateRequest'
      responses:
        204:
          description: Successfully updated referral task
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${OfferApiFunctionV2.Arn}:live/invocations
        httpMethod: POST
        passthroughBehavior: when_no_match
        type: aws_proxy
components:
  schemas:
    ReferralReasonCodeCore:
      description: '`reason_code` associated to a cancelled or closed referral.

        '
      type: object
      properties:
        reason_code:
          type: string
          enum:
          - datetime_change
          - client_request
          - client_hospitalization
          - client_passed_away
          - client_refused_service
          - processing_error
          - other
    InboxReferralCarePlanInterventionResponse:
      allOf:
      - $ref: '#/components/schemas/CarePlanInterventionCore'
      - type: object
        properties:
          goals:
            type: array
            items:
              title: InboxCarePlanInterventionGoalCore
              type: object
              properties:
                name:
                  type: string
              required:
              - name
          client_task_id:
            type: string
            format: uuid
    CareTypeCore:
      type: string
      enum:
      - psw
      - nursing
    InboxReferralDetailResponse:
      description: 'API response for the complete representation of an assigned referral on the inbox API.

        This schema is similar to the `InboxAnonReferral` except that it includes the complete

        representation of the referral instead of the anonymous representation.

        '
      type: object
      properties:
        referral:
          title: InboxReferralDetailReferralResponse
          allOf:
          - $ref: '#/components/schemas/ReferralReasonCodeCore'
          - type: object
            properties:
              id:
                type: string
                format: uuid
              sequence_id:
                type: string
                format: uuid
              offer_id:
                type: string
                format: uuid
              shift_id:
                type: string
                format: uuid
              care_type:
                $ref: '#/components/schemas/CareTypeCore'
              referral_type:
                $ref: '#/components/schemas/ReferralTypeCore'
              start_at:
                type: string
                format: date-time
              end_at:
                type: string
                format: date-time
              comment:
                type: string
              cancellation_comment:
                type: string
                maxLength: 1000
              status:
                $ref: '#/components/schemas/ReferralStatusCore'
              created_at:
                type: string
                format: date-time
              updated_at:
                type: string
                format: date-time
            required:
            - id
            - care_type
            - referral_type
            - start_at
            - status
            - created_at
        demand:
          $ref: '#/components/schemas/OrganizationLeanCore'
        alayacare:
          $ref: '#/components/schemas/InboxReferralAlayaCareResponse'
        case_manager:
          $ref: '#/components/schemas/CaseManagerCore'
        price:
          $ref: '#/components/schemas/PriceCore'
        client:
          $ref: '#/components/schemas/InboxClientResponse'
        service:
          title: InboxReferralDetailServiceResponse
          type: object
          properties:
            id:
              type: string
              format: uuid
            use_client_address:
              type: boolean
            address:
              $ref: '#/components/schemas/AddressCore'
            name:
              type: string
              minLength: 1
            start_at:
              type: string
              format: date-time
            expected_start_at:
              type: string
              format: date-time
            end_at:
              type: string
              format: date-time
            instructions:
              type: string
            notes:
              type: string
            skills:
              type: array
              items:
                type: string
            custom_fields:
              type: array
              items:
                $ref: '#/components/schemas/CustomFieldCore'
          required:
          - id
          - name
        visits:
          type: array
          items:
            $ref: '#/components/schemas/InboxReferralVisitResponse'
        revision:
          $ref: '#/components/schemas/ReferralRevisionResponse'
      required:
      - referral
      - demand
      - service
      - client
      - revision
    InboxReferralCarePlanResponse:
      type: object
      properties:
        name:
          type: string
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        status:
          type: string
        diagnoses:
          type: array
          items:
            $ref: '#/components/schemas/CarePlanDiagnosisCore'
        goals:
          type: array
          items:
            $ref: '#/components/schemas/InboxCarePlanGoalResponse'
        interventions:
          type: array
          items:
            $ref: '#/components/schemas/InboxReferralCarePlanInterventionResponse'
        updated_at:
          type: string
          format: date-time
      required:
      - name
      - start_date
    PriceCore:
      type: object
      properties:
        rate:
          type: number
          format: decimal
          description: The dollar amount for offer per unit.
          example: 30.0
        unit:
          type: string
          description: The unit for the rate.
          enum:
          - per_visit
          - per_hour
          - amount
      required:
      - rate
      - unit
    CarePlanInterventionCore:
      type: object
      properties:
        description:
          type: string
        end_date:
          type: string
          format: date
        external_link:
          title: CarePlanInterventionExternalLinkCore
          type: object
          properties:
            label:
              type: string
            url:
              type: string
          required:
          - label
          - url
        has_duration:
          type: boolean
        is_from_library:
          type: boolean
        is_required:
          type: boolean
        name:
          type: string
        rank:
          type: integer
        recurrence:
          title: CarePlanInterventionRecurrenceCore
          type: object
          properties:
            count:
              type: integer
            frequency:
              type: string
            interval:
              type: integer
            weekdays:
              type: array
              items:
                type: string
            monthday:
              type: integer
            available_from:
              type: string
            available_to:
              type: string
          required:
          - frequency
          - interval
        recurrence_type:
          type: string
        start_date:
          type: string
          format: date
        status:
          type: string
        timezone:
          type: string
        type:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - has_duration
      - is_required
      - name
      - rank
      - recurrence_type
      - start_date
      - status
      - type
    PageNumberCore:
      type: integer
      minimum: 1
      default: 1
    CaseManagerCore:
      type: object
      properties:
        name:
          type: string
        phone_number:
          type: string
        fax_number:
          type: string
        email:
          type: string
    InboxFormTemplateFieldResponse:
      allOf:
      - $ref: '#/components/schemas/FormTemplateFieldCore'
      - type: object
        properties:
          field_id:
            type: string
            format: uuid
    InboxReferralAlayaCareResponse:
      type: object
      properties:
        authorizations:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizationCore'
        care_plan:
          $ref: '#/components/schemas/InboxReferralCarePlanResponse'
        form_templates:
          type: array
          items:
            $ref: '#/components/schemas/InboxFormTemplateDetailResponse'
    InboxReferralCollectionResponse:
      description: 'API response for the core representation of a referral response on the inbox API.

        '
      type: object
      properties:
        referral:
          title: InboxReferralCollectionReferralResponse
          allOf:
          - $ref: '#/components/schemas/ReferralReasonCodeCore'
          - type: object
            properties:
              id:
                type: string
                format: uuid
              sequence_id:
                type: string
                format: uuid
              offer_id:
                type: string
                format: uuid
              shift_id:
                type: string
                format: uuid
              care_type:
                $ref: '#/components/schemas/CareTypeCore'
              referral_type:
                $ref: '#/components/schemas/ReferralTypeCore'
              start_at:
                type: string
                format: date-time
              end_at:
                type: string
                format: date-time
              status:
                $ref: '#/components/schemas/ReferralStatusCore'
              created_at:
                type: string
                format: date-time
              updated_at:
                type: string
                format: date-time
            required:
            - id
            - care_type
            - referral_type
            - start_at
            - status
            - created_at
        revision:
          title: InboxReferralCollectionRevisionResponse
          type: object
          properties:
            revision_group_id:
              type: string
              format: uuid
            revision_number:
              type: integer
              minimum: 1
          required:
          - revision_group_id
          - revision_number
      required:
      - referral
      - revision
    AuthorizationCore:
      type: object
      properties:
        authorization_number:
          type: string
        authorization_status:
          type: string
        end_date:
          type: string
          format: date
        first_day_of_week:
          type: integer
        id:
          type: integer
        import_id:
          type: string
        member_number:
          type: string
        notes:
          type: string
        program_id:
          type: string
        custom_number_of_days:
          type: integer
        rule_type:
          type: string
        rule_custom:
          type: number
          format: decimal
        rule_daily:
          type: number
          format: decimal
        rule_weekly:
          type: number
          format: decimal
        rule_monthly:
          type: number
          format: decimal
        rule_period:
          type: number
          format: decimal
        rule_monday:
          type: number
          format: decimal
        rule_tuesday:
          type: number
          format: decimal
        rule_wednesday:
          type: number
          format: decimal
        rule_thursday:
          type: number
          format: decimal
        rule_friday:
          type: number
          format: decimal
        rule_saturday:
          type: number
          format: decimal
        rule_sunday:
          type: number
          format: decimal
        start_date:
          type: string
          format: date
      required:
      - authorization_status
      - first_day_of_week
      - rule_type
      - start_date
    CarePlanGoalCore:
      type: object
      properties:
        description:
          type: string
        end_date:
          type: string
          format: date
        is_from_library:
          type: boolean
        is_primary:
          type: boolean
        last_updated_progress:
          title: GoalLastUpdatedProgressCore
          type: object
          properties:
            comment:
              type: string
            percentage:
              type: integer
            completed:
              type: boolean
        name:
          type: string
        progress_type:
          type: string
        rank:
          type: integer
        start_date:
          type: string
          format: date
        status:
          type: string
        type:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - name
      - start_date
      - is_primary
      - type
      - progress_type
    PageCore:
      description: Root page schema for returning collections.
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageNumberCore'
        items_per_page:
          $ref: '#/components/schemas/ItemsPerPageCore'
        total_items:
          type: integer
          minimum: 0
        total_pages:
          type: integer
          minimum: 0
      required:
      - page
      - items_per_page
      - total_items
      - total_pages
    CustomFieldCore:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        value:
          type: string
      required:
      - name
      - value
    AllergyCore:
      type: object
      properties:
        name:
          type: string
        category:
          type: string
        severity:
          type: string
        start_date:
          type: string
          format: date
        treatment:
          type: string
    SortOrderCore:
      type: string
      enum:
      - asc
      - desc
      default: desc
    InboxReferralVisitTaskResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
        description:
          type: string
        is_required:
          type: boolean
      required:
      - id
      - name
      - is_required
    InboxClientTasksUpdateRequest:
      type: object
      properties:
        client_tasks:
          type: array
          minItems: 1
          items:
            title: InboxClientTasksUpdateItemRequest
            type: object
            properties:
              id:
                type: string
                format: uuid
              inbox_id:
                type: string
            required:
            - id
            - inbox_id
      required:
      - client_tasks
    ClientCore:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressCore'
        contacts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              first_name:
                type: string
              last_name:
                type: string
              address:
                type: object
                properties:
                  city:
                    type: string
                  state:
                    type: string
                  zip:
                    type: string
                  country:
                    type: string
                  name:
                    type: string
                  address:
                    type: string
                  address_suite:
                    type: string
                  latitude:
                    type: number
                    format: double
                    minimum: -90
                    maximum: 90
                  longitude:
                    type: number
                    format: double
                    minimum: -180
                    maximum: 180
              contact_type:
                type: string
              email:
                type: string
                format: email
              is_active:
                type: boolean
                default: true
              is_emergency:
                type: boolean
              phone_number:
                description: Main phone number.
                type: string
              phone_other:
                type: string
              phone_personal:
                type: string
              language:
                type: string
              relationship:
                type: string
        demographics:
          type: object
          properties:
            first_name:
              type: string
              minLength: 1
            last_name:
              type: string
              minLength: 1
            email:
              type: string
              format: email
            phone_number:
              description: Main phone number.
              type: string
            phone_other:
              type: string
            phone_personal:
              type: string
            date_of_birth:
              type: string
              format: date
            gender:
              type: string
            language:
              type: string
          required:
          - first_name
          - last_name
        allergies:
          type: array
          items:
            $ref: '#/components/schemas/AllergyCore'
        risks:
          type: array
          items:
            $ref: '#/components/schemas/RiskCore'
        diagnoses:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              is_primary:
                type: boolean
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              treatment:
                type: string
        surgeries:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              details:
                type: string
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldCore'
      required:
      - demographics
      - address
    InboxReferralPageResponse:
      allOf:
      - $ref: '#/components/schemas/PageCore'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/InboxReferralCollectionResponse'
        required:
        - items
    ReferralStatusCore:
      type: string
      enum:
      - assigned
      - processed
      - cancelled
    ItemsPerPageCore:
      type: integer
      minimum: 1
      default: 100
    InboxFormTemplateDetailResponse:
      allOf:
      - $ref: '#/components/schemas/FormTemplateCore'
      - type: object
        properties:
          fields:
            type: array
            items:
              $ref: '#/components/schemas/InboxFormTemplateFieldResponse'
          form_template_id:
            type: string
            format: uuid
          demand_persona_id:
            type: string
            format: uuid
    InboxClientResponse:
      allOf:
      - $ref: '#/components/schemas/ClientCore'
      - type: object
        properties:
          id:
            type: string
            format: uuid
        required:
        - id
    InboxReferralVisitResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        instructions:
          type: string
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/InboxReferralVisitTaskResponse'
      required:
      - id
      - start_at
      - end_at
    CarePlanDiagnosisCore:
      type: object
      properties:
        description:
          type: string
        end_date:
          type: string
          format: date
        is_from_library:
          type: boolean
        is_primary:
          type: boolean
        name:
          type: string
        rank:
          type: integer
        start_date:
          type: string
          format: date
        status:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - name
      - start_date
      - is_primary
    FormTemplateCore:
      type: object
      properties:
        admin_eyes_only:
          type: boolean
        approve_automatically:
          type: boolean
        clinical_event_name:
          type: string
        display_instructions_in_pdf:
          type: boolean
        display_report:
          type: boolean
        exclude_from_shift_report:
          type: boolean
        form_type:
          type: string
        id:
          type: integer
        instructions:
          type: string
        language_code:
          type: string
        name:
          type: string
        notify_alert_queue:
          type: boolean
        pre_populate:
          type: boolean
        requires_clock_in:
          type: boolean
        schema_id:
          type: string
          format: uuid
        schema_version:
          type: integer
        visit_link_required:
          type: boolean
      required:
      - admin_eyes_only
      - approve_automatically
      - display_instructions_in_pdf
      - display_report
      - exclude_from_shift_report
      - form_type
      - id
      - language_code
      - name
      - notify_alert_queue
      - pre_populate
      - requires_clock_in
      - schema_id
      - schema_version
      - visit_link_required
    RiskCore:
      type: object
      properties:
        name:
          type: string
        category:
          type: string
          example: allergy
        severity:
          type: integer
        start_date:
          type: string
          format: date
    InboxCarePlanGoalResponse:
      allOf:
      - $ref: '#/components/schemas/CarePlanGoalCore'
      - type: object
        properties:
          diagnoses:
            type: array
            items:
              title: InboxCarePlanGoalDiagnosisCore
              type: object
              properties:
                name:
                  type: string
              required:
              - name
    ReferralRevisionResponse:
      type: object
      properties:
        revision_group_id:
          type: string
          format: uuid
        revision_number:
          type: integer
          minimum: 1
        revision_reasons:
          type: array
          items:
            type: string
        revision_comment:
          type: string
        is_latest_revision:
          type: boolean
      required:
      - revision_group_id
      - revision_number
      - is_latest_revision
    ReferralTypeCore:
      type: string
      enum:
      - visit
      - service
    FormTemplateFieldCore:
      type: object
      properties:
        field_tag:
          type: string
        field_type:
          type: string
        id:
          type: integer
        instructions:
          type: string
        json_logic:
          type: object
        label:
          type: string
        parent_id:
          type: integer
        rank:
          type: integer
        required:
          type: boolean
        settings:
          type: object
      required:
      - field_type
      - id
      - label
      - parent_id
      - rank
      - required
    OrganizationLeanCore:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
      required:
      - id
      - name
    InboxReferralCancelRequest:
      allOf:
      - $ref: '#/components/schemas/ReferralReasonCodeCore'
    AddressCore:
      type: object
      properties:
        name:
          type: string
        address:
          type: string
          minLength: 1
        address_suite:
          type: string
        city:
          type: string
          minLength: 1
        state:
          type: string
          minLength: 1
        zip:
          type: string
          minLength: 1
        country:
          type: string
          minLength: 1
        latitude:
          type: number
          format: double
          minimum: -90
          maximum: 90
        longitude:
          type: number
          format: double
          minimum: -180
          maximum: 180
      required:
      - address
      - city
      - state
      - zip
      - country
    SortByCore:
      type: string
      enum:
      - last_modified
      default: last_modified
  parameters:
    ItemsPerPageParam:
      in: query
      name: items_per_page
      schema:
        $ref: '#/components/schemas/ItemsPerPageCore'
    ShiftIdQueryParam:
      in: query
      name: shift_id
      schema:
        type: string
        format: uuid
    RevisionsQueryParam:
      in: query
      name: revisions
      schema:
        type: string
        description: Filter in all revisions for a given referral, or only the latest revision, or only the archived revision(s).
        enum:
        - all
        - latest
        - archived
        default: latest
    PageNumberParam:
      in: query
      name: page
      schema:
        $ref: '#/components/schemas/PageNumberCore'
    SortOrderParam:
      in: query
      name: sort_order
      schema:
        $ref: '#/components/schemas/SortOrderCore'
    OfferIdQueryParam:
      in: query
      name: offer_id
      schema:
        type: string
        format: uuid
    ReferralIdPathParam:
      in: path
      name: referral_id
      schema:
        type: string
        format: uuid
      required: true
    SortByParam:
      in: query
      name: sort_by
      schema:
        $ref: '#/components/schemas/SortByCore'
  securitySchemes:
    CognitoAuthorizer:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools
      x-amazon-apigateway-authorizer:
        type: cognito_user_pools
        providerARNs:
        - Fn::Sub: '{{resolve:ssm:/${StackName}/${UserPoolArnSSMParameterName}}}'
x-amazon-apigateway-request-validators:
  body:
    validateRequestBody: true
    validateRequestParameters: false
  params:
    validateRequestBody: false
    validateRequestParameters: true
  params-and-body:
    validateRequestBody: true
    validateRequestParameters: true
x-amazon-apigateway-request-validator: params
x-amazon-apigateway-gateway-responses:
  BAD_REQUEST_BODY:
    statusCode: 400
    responseTemplates:
      application/json: '{"message": $context.error.messageString, "description": "$context.error.validationErrorString"}'