Thriva Results API API

openapi: 3.0.2
info:
  title: Platform API V1 Appointments API Results API API
  version: '1.0'
  description: End-to-end API to send tests kits and process samples
servers:
- url: https://api.thriva.io
- url: https://api.euw2.sandbox.thriva.io/
tags:
- name: Results API
paths:
  /v1/result-sets:
    get:
      summary: Fetch Results
      description: Lists all of your results
      tags:
      - Results API
      parameters:
      - in: query
        name: filter[startDate]
        schema:
          type: string
        description: The date (UTC) from which results will be retrieved (YYYY-MM-DD)
        required: false
      - in: query
        name: filter[endDate]
        schema:
          type: string
        description: The date (UTC) to which results will be retrieved (YYYY-MM-DD)
        required: false
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          $ref: '#/components/responses/ResultSetsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeResponse'
  /v1/result-sets/{result_set_id}:
    get:
      summary: Fetch a Result
      tags:
      - Results API
      parameters:
      - name: result_set_id
        in: path
        required: true
        schema:
          type: string
          description: The result set ID for a complete Order
          example: RS-8719EAF0-6B39-46B5-86DA-AF11155F3B65
      - $ref: '#/components/parameters/ResultSetIncludes'
      responses:
        '200':
          $ref: '#/components/responses/ResultSetResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeResponse'
components:
  parameters:
    PageNumber:
      in: query
      name: page[number]
      schema:
        type: integer
      description: The page that will be returned
      required: false
    ResultSetIncludes:
      name: include
      description: A comma separated list of relationship objects to include in response
      in: query
      schema:
        type: string
        example: test_profiles,biomarker_results,escalations
    PageSize:
      in: query
      name: page[size]
      description: The amount of items per page
      required: false
      schema:
        type: integer
        minimum: 10
        maximum: 100
  schemas:
    InvalidAccessTokenError:
      type: object
      required:
      - title
      properties:
        title:
          type: string
          description: Title of the error
          example: invalid access token
    Reporter:
      type: object
      required:
      - id
      - type
      - attributes
      properties:
        id:
          description: Immutable identifier for Reporter
          type: string
          example: RPTR-B4D0F0E2-C612-407C-A8FC-F9F31F44F226
        type:
          type: string
          example: reporter
        attributes:
          type: object
          properties:
            title:
              type: string
              enum:
              - Dr Mr Mrs Ms Miss Mx
              example: Dr
            first_name:
              type: string
              example: John
            last_name:
              type: string
              example: Doe
            email:
              type: string
              example: john.doe@example.com
    ResultSet:
      type: object
      required:
      - id
      - type
      - attributes
      - relationships
      properties:
        id:
          description: Immutable identifier for Result Set
          type: string
          example: RS-8719EAF0-6B39-46B5-86DA-AF11155F3B65
        type:
          type: string
          example: result_set
        attributes:
          type: object
          properties:
            result_date:
              description: DateTime (in ISO8601 format) for when the result has been created
              type: string
              example: '2023-02-12T11:00:00Z'
            sample_taken_at:
              description: DateTime (in ISO8601 format) for when the sample was received by the lab
              type: string
              example: '2023-02-11T08:00:00Z'
            sample_booked_in_at:
              description: DateTime (in ISO8601 format) for when the sample was received by the lab and ready to be analysed
              type: string
              example: '2023-02-12T10:00:00Z'
            sample_processed_at:
              description: DateTime (in ISO8601 format) for when the sample was analysed at the lab, and results have been made available
              type: string
              example: '2023-02-12T11:00:00Z'
            sample_reference:
              description: The reference number that will appear on the test kit is a unique number assigned to each kit. This reference will also be used by the lab to refer to the test results if a result were to be escalated due to falling outside of the expected ranges
              type: string
              example: T123456789
            status:
              description: The current status of the Result Set
              type: string
              enum:
              - complete
              - results_to_follow
        relationships:
          type: object
          properties:
            test_profiles:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: Test Profile ID
                        type: string
                        example: AB12
                      type:
                        type: string
                        example: test_profile
            biomarker_results:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: Biomarker Result ID
                        type: string
                        example: BR-7CLGY37N8WLBE0E8AAULAPBCBMF9ATVZFJ70
                      type:
                        type: string
                        example: biomarker_result
            escalations:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: Escalation ID
                        type: string
                        example: ESC-0A657293-28A9-47C1-A119-126540BCBB5A
                      type:
                        type: string
                        example: escalation
            reports:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Report'
            pdf_result_attachment:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      description: Result Set Attachment ID
                      type: string
                      example: F14VHYB35EF7F5O2
                    type:
                      type: string
                      example: result_set_attachment
    Report:
      type: object
      required:
      - id
      - type
      - attributes
      - relationships
      properties:
        id:
          description: Report ID
          type: string
          example: REP-CFD18A5C-4F68-4C45-BFBC-7D9A1C35A4C6
        type:
          type: string
          example: report
        attributes:
          type: object
          properties:
            report_summary:
              description: Clinician-authored narrative for the report. Populated once `status` is `complete`.
              type: string
              example: Hi John, these results are excellent.
            status:
              description: Status of the report
              type: string
              enum:
              - complete
              example: complete
        relationships:
          type: object
          properties:
            reporter:
              $ref: '#/components/schemas/Reporter'
            biomarker_comments:
              $ref: '#/components/schemas/BiomarkerComment'
    TestProfile:
      type: object
      required:
      - id
      - type
      - attributes
      - relationships
      properties:
        id:
          description: Immutable identifier for Test Profile
          type: string
          example: AB12
        type:
          type: string
          example: test_profile
        attributes:
          type: object
          properties:
            name:
              type: string
              example: B12 (Active)
            code:
              type: string
              example: AB12
            description:
              type: string
              example: This is a short description of the test profile, how it affects the human body, and why it is helpful to be monitored.
            sample_type:
              type: string
              enum:
              - blood
              - saliva
            collection_methods:
              type: array
              items:
                example:
                - finger_prick
                - venous
            collection_tube:
              type: string
              description: The collection tube needed to test this test profile
              example: EDTA/Purple tube
        relationships:
          type: object
          properties:
            biomarkers:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: Biomarker ID
                        type: string
                        example: ALP
                      type:
                        type: string
                        example: biomarker
    BiomarkerResult:
      type: object
      required:
      - id
      - type
      - attributes
      - relationships
      properties:
        id:
          description: Unique identifier for Biomarker Result
          type: string
          example: BR-7CLGY37N8WLBE0E8AAULAPBCBMF9ATVZFJ70
        type:
          type: string
          example: biomarker_result
        attributes:
          type: object
          properties:
            code:
              description: Biomarker code for this Biomarker Result
              type: string
              example: ALP
            successful:
              type: boolean
              example: true
            failure_reason:
              type: string
              nullable: true
              enum:
              - clotted
              - contaminated
              - delay
              - foreign_object
              - haemolysed
              - icteric
              - insufficient
              - lab_error
              - lid_swap
              - lipaemic
              - mismatch
              - no_sample_received
              - sample_leaked
              - unknown
              - unlabelled
            failure_reason_description:
              type: string
              nullable: true
              description: Human-readable description of the failure reason
            abnormal_flag:
              type: string
              nullable: true
              example: A
            escalation_level:
              description: The escalation level for this biomarker result
              type: string
              enum:
              - very_high
              - high
              - medium
              - low
              - very_low
              - not_escalated
            result_type:
              type: string
              enum:
              - numeric
              - string
            result_value:
              type: string
              example: '1.78'
            result_unit:
              type: string
              example: umol/L
            result_operator:
              type: string
              nullable: true
              enum:
              - LESS_THAN
              - LESS_THAN_OR_EQUAL
              - GREATER_THAN
              - GREATER_THAN_OR_EQUAL
            notes:
              description: An array of notes returned from the Lab about this biomarker result
              type: array
              items:
                type: string
                example: Your Creatinine levels are high. Please discuss this with your GP.
            reference_ranges:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: Normal
                  lower_bound:
                    type: string
                    nullable: true
                    example: '50.0000'
                  upper_bound:
                    type: string
                    nullable: true
                    example: '250.0000'
                  operator:
                    type: string
                    nullable: true
                    example: LESS_THAN
                    enum:
                    - LESS_THAN
                    - LESS_THAN_OR_EQUAL
                    - GREATER_THAN
                    - GREATER_THAN_OR_EQUAL
                  severity_level:
                    type: integer
                    nullable: false
                    minimum: 10
                    maximum: 50
                    example: 20
            interpretation:
              description: Provides interpretation for results. String results will contain a display value and sentiment for the result. Numeric results will contain a display value and matched reference range
              type: object
              nullable: true
              properties:
                display_value:
                  description: For numeric results the display_value joins the operator and numeric value together. For string results, the display_value formats the string correctly and can provide a more human understandable interpretation of the result. e.g. For an antibody test, the string_result might be `positive` while the `display_value` would be `immune`.
                  type: string
                  example: '100.0'
                  nullable: true
                sentiment:
                  description: The sentiment associated with string result interpretations. Can be used to decide how to display results on the frontend (i.e. positive sentiment might be highlighted in green). Can be positive, negative, or neutral
                  type: string
                  example: positive
                  nullable: true
                  enum:
                  - positive
                  - negative
                  - neutral
                matched_reference_range:
                  description: The reference range that the result value falls within
                  type: object
                  nullable: true
                  properties:
                    name:
                      type: string
                      example: Normal
                    severity_level:
                      type: integer
                      example: 20
        relationships:
          type: object
          properties:
            test_profiles:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: Test Profile ID
                        type: string
                        example: AB12
                      type:
                        type: string
                        example: test_profile
    Escalation:
      type: object
      required:
      - id
      - type
      - attributes
      properties:
        id:
          description: Escalation ID
          type: string
          example: ESC-0A657293-28A9-47C1-A119-126540BCBB5A
        type:
          type: string
          example: escalation
        attributes:
          type: object
          required:
          - level
          - acknowledgment_due_by
          - acknowledged_at
          - status
          properties:
            level:
              description: The level of the escalation
              type: string
              example: very_high
              enum:
              - very_high
              - high
              - medium
              - low
              - very_low
              - not_escalated
            acknowledgment_due_by:
              description: When the escalation needs to be acknowledged by
              type: string
              format: date-time
              nullable: true
            acknowledged_at:
              description: When you acknowledged the escalation
              type: string
              format: date-time
              nullable: true
            status:
              description: The current status of the escalation
              type: string
              enum:
              - acknowledged
              - awaiting_acknowledgment
              - no_acknowledgment_required
              - archived
    UnsupportedMediaTypeError:
      type: object
      required:
      - title
      - detail
      properties:
        title:
          type: string
          description: Title of the error
          example: unsupported media type
        detail:
          type: string
          example: This endpoint only supports application/vnd.api+json
    Pagination:
      type: object
      required:
      - self
      - current
      properties:
        self:
          type: string
          description: The link that generated the current response document
          example: http://example.com/articles?page[number]=3&page[size]=1
        current:
          type: string
          description: The link for the current page
          example: http://example.com/articles?page[number]=3&page[size]=1
        first:
          type: string
          description: The link to the first page
          example: http://example.com/articles?page[number]=1&page[size]=1
        prev:
          type: string
          description: The link to the previous page
          example: http://example.com/articles?page[number]=2&page[size]=1
        next:
          type: string
          description: The link to the next page
          example: http://example.com/articles?page[number]=4&page[size]=1
        last:
          type: string
          description: The link to the last page
          example: http://example.com/articles?page[number]=13&page[size]=1
    NotFoundError:
      type: object
      required:
      - title
      - detail
      properties:
        title:
          type: string
          description: Title of the error
          example: resource not found
    ForbiddenError:
      type: object
      required:
      - title
      properties:
        title:
          type: string
          description: Title of the error
          example: action not permitted
    BiomarkerComment:
      description: Beta feature, disabled by default. When not enabled for your organisation, `report.relationships.biomarker_comments.data` will be an empty array.
      type: object
      required:
      - id
      - type
      - attributes
      properties:
        id:
          description: Immutable identifier for Biomarker Comment
          type: string
          example: '1286'
        type:
          type: string
          example: biomarker_comment
        attributes:
          type: object
          properties:
            comment:
              description: Beta feature, disabled by default. Automated rule-derived annotation for the associated biomarker result, based on the biomarker value, subject sex, and any previous result. Not authored by the clinician; the clinician's narrative is on `report.attributes.report_summary`.
              type: string
              example: Your ferritin levels are low. We would advise following up with your GP.
        relationships:
          type: object
          properties:
            biomarker_result:
              $ref: '#/components/schemas/BiomarkerResult'
    BadRequestError:
      type: object
      required:
      - title
      - detail
      - source
      properties:
        title:
          type: string
          description: Title of the error
          example: invalid field
        detail:
          type: string
          example: field_name.example must be a string
        source:
          type: object
          required:
          - pointer
          properties:
            pointer:
              description: A RFC6901 compliant JSON pointer to the attribute that caused the error
              type: string
              example: /data/field_name/example
  responses:
    ResultSetsResponse:
      description: An array of Result Set
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/ResultSet'
              links:
                $ref: '#/components/schemas/Pagination'
    ResultSetResponse:
      description: Successful request
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
            - data
            properties:
              data:
                $ref: '#/components/schemas/ResultSet'
              included:
                type: array
                items:
                  anyOf:
                  - $ref: '#/components/schemas/BiomarkerResult'
                  - $ref: '#/components/schemas/TestProfile'
                  - $ref: '#/components/schemas/Escalation'
    UnauthorizedResponse:
      description: Unauthorized response
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
            - errors
            properties:
              errors:
                type: array
                items:
                  anyOf:
                  - $ref: '#/components/schemas/InvalidAccessTokenError'
    BadRequestResponse:
      description: Bad request
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
            - errors
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/BadRequestError'
    UnsupportedMediaTypeResponse:
      description: Unsupported media type response
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
            - errors
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/UnsupportedMediaTypeError'
    ForbiddenResponse:
      description: Action forbidden response
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
            - errors
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ForbiddenError'
    NotFoundResponse:
      description: Resource not found
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
            - errors
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/NotFoundError'