WHOOP Partner API

openapi: 3.0.1
info:
  title: WHOOP Activity ID Mapping Partner API
  description: Utility endpoints for activity ID mapping
servers:
- url: https://api.prod.whoop.com/developer
tags:
- name: Partner
  description: Endpoints for trusted WHOOP partner operations
paths:
  /v2/partner/development/add-test-data:
    post:
      tags:
      - Partner
      summary: Generate test data for partner development
      description: Generates test user and lab requisition data for partner integration testing. This endpoint is only available in non-production environments
      operationId: addTestData
      responses:
        '204':
          description: Test data generated successfully
        '404':
          description: Not available in production environments
        '500':
          description: Failed to generate test data
      security:
      - Trusted Partner: []
  /v2/partner/requisition/{id}:
    get:
      tags:
      - Partner
      summary: Get a lab requisition by ID
      description: Retrieves a lab requisition with its associated service requests by its unique identifier. The requesting partner must be an owner of the lab requisition.
      operationId: getLabRequisitionById
      parameters:
      - name: id
        in: path
        description: Unique identifier of the lab requisition
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Lab requisition found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabRequisition'
        '404':
          description: Lab requisition not found or partner is not an owner
      security:
      - Trusted Partner: []
  /v2/partner/service-request/{id}:
    get:
      tags:
      - Partner
      summary: Get a service request by ID
      description: Retrieves a service request by its unique identifier. The requesting partner must be an owner of the service request.
      operationId: getServiceRequestById
      parameters:
      - name: id
        in: path
        description: Unique identifier of the service request
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Service request found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRequest'
        '404':
          description: Service request not found or partner is not an owner
      security:
      - Trusted Partner: []
  /v2/partner/token:
    post:
      tags:
      - Partner
      summary: Request a partner client token
      description: Exchanges partner client credentials for an access token.
      operationId: requestToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerTokenRequest'
      responses:
        '200':
          description: Token issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerTokenResponse'
        '401':
          description: Invalid client credentials
  /v2/partner/requisition/{id}/status:
    patch:
      tags:
      - Partner
      summary: Update lab requisition service request statuses
      description: Updates the task business status on all service requests belonging to the requisition. The requesting partner must be an owner.
      operationId: updateLabRequisitionStatus
      parameters:
      - name: id
        in: path
        description: Unique identifier of the lab requisition
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequestStatusRequest'
      responses:
        '204':
          description: Service request statuses updated successfully
        '404':
          description: Lab requisition not found or partner is not an owner
      security:
      - Trusted Partner: []
  /v2/partner/service-request/{id}/status:
    patch:
      tags:
      - Partner
      summary: Update service request status
      description: Updates the business status of a service request task. The requesting partner must be an owner of the service request.
      operationId: updateServiceRequestStatus
      parameters:
      - name: id
        in: path
        description: Unique identifier of the service request
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequestStatusRequest'
      responses:
        '200':
          description: Service request status updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRequest'
        '404':
          description: Service request not found or partner is not an owner
      security:
      - Trusted Partner: []
  /v2/partner/service-request/{id}/results:
    post:
      tags:
      - Partner
      summary: Create diagnostic report results for a service request
      description: Creates a diagnostic report with results for a service request. The requesting partner must be an owner of the service request.
      operationId: uploadDiagnosticReportResults
      parameters:
      - name: id
        in: path
        description: Unique identifier of the service request
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiagnosticReportCreateRequest'
      responses:
        '201':
          description: Diagnostic report created successfully
        '404':
          description: Service request not found or partner is not an owner
      security:
      - Trusted Partner: []
components:
  schemas:
    Appointment:
      required:
      - service_request_ids
      - start_time
      type: object
      properties:
        service_request_ids:
          type: array
          description: The service request IDs associated with this appointment
          items:
            type: string
            description: The service request IDs associated with this appointment
            format: uuid
        start_time:
          type: string
          description: The start time of the appointment
          format: date-time
      description: Appointment information
      oneOf:
      - $ref: '#/components/schemas/UnilabsAppointment'
    Patient:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the patient
          format: uuid
    PartnerTokenResponse:
      type: object
      properties:
        access_token:
          type: string
        expires_in:
          type: integer
          format: int32
        token_type:
          type: string
    UnilabsAppointment:
      required:
      - service_request_ids
      - start_time
      type: object
      properties:
        slot_id:
          type: string
          description: External slot identifier used when booking the appointment
        collection_address:
          $ref: '#/components/schemas/UnilabsCollectionAddress'
        service_request_ids:
          type: array
          description: The service request IDs associated with this appointment
          items:
            type: string
            description: The service request IDs associated with this appointment
            format: uuid
        start_time:
          type: string
          description: The start time of the appointment
          format: date-time
    ServiceRequestStatusRequest:
      type: object
      properties:
        task_business_status:
          type: string
          description: Task business status for workflow tracking (e.g., 'Specimen collected', 'Results pending')
        reason:
          type: string
          description: Optional reason for the task business status change
    PartnerTokenRequest:
      required:
      - client_id
      - client_secret
      type: object
      properties:
        client_id:
          type: string
          description: client id for this partner
        client_secret:
          type: string
        scope:
          type: string
          description: scope for this token request
        grant_type:
          type: string
          description: grant type for this token request
    ServiceRequest:
      required:
      - code
      - id
      - intent
      - status
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the service request
          format: uuid
        status:
          type: string
          description: FHIR status of the service request
        intent:
          type: string
          description: FHIR intent of the service request
        code:
          type: string
          description: Code identifying the specific service or procedure requested
        task_business_status:
          type: string
          description: Task business status for workflow tracking (e.g., 'Specimen collected', 'Results pending')
        task_description:
          type: string
          description: Task description - free text explanation of what needs to be performed
    UnilabsCollectionAddress:
      required:
      - area
      - building
      - emirate
      type: object
      properties:
        building:
          type: string
          description: Building name or number
        area:
          type: string
          description: Area or district
        emirate:
          type: string
          description: Emirate
        landmark:
          type: string
          description: Nearby landmark
        flat_no:
          type: string
          description: Flat or apartment number
      description: The collection address for this appointment
    PatientCore:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the patient
          format: uuid
      description: Patient information
      oneOf:
      - $ref: '#/components/schemas/Patient'
      - $ref: '#/components/schemas/UnilabsPatient'
    UnilabsPatient:
      required:
      - birth_date
      - first_name
      - id
      - last_name
      type: object
      properties:
        first_name:
          type: string
          description: First name of the patient
        last_name:
          type: string
          description: Last name of the patient
        birth_date:
          type: string
          description: Birth date of the patient
          format: date
        gender:
          type: string
          description: Gender of the patient
        email:
          type: string
          description: Email address of the patient
        phone:
          type: string
          description: Phone number of the patient
        nationality:
          type: string
          description: Nationality of the patient
        id:
          type: string
          description: Unique identifier for the patient
          format: uuid
        emirates_id:
          type: string
          description: Emirates ID of the patient
        passport_no:
          type: string
          description: Passport number of the patient
    CreateObservationRequest:
      type: object
      properties:
        value_numeric:
          type: number
          description: the decimal value for this observation, if there is one
          format: double
        value_text:
          type: string
          description: the text value for this observation, if there is one
        unit:
          type: string
          description: the unit of this observation value, if there is one
        status:
          type: string
          description: the status of this observation
        code:
          type: string
          description: the code for this observation
      description: optional list of observations to attach to the diagnostic report
    LabRequisition:
      required:
      - appointments
      - created_at
      - id
      - patient
      - service_requests
      - updated_at
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the lab requisition
          format: uuid
        created_at:
          type: string
          description: Timestamp when the lab requisition was created
          format: date-time
        updated_at:
          type: string
          description: Timestamp when the lab requisition was last updated
          format: date-time
        service_requests:
          type: array
          description: The service requests associated with this lab requisition
          items:
            $ref: '#/components/schemas/ServiceRequest'
        patient:
          $ref: '#/components/schemas/PatientCore'
        appointments:
          type: array
          description: The appointments associated with this lab requisition
          items:
            $ref: '#/components/schemas/Appointment'
    DiagnosticReportCreateRequest:
      type: object
      properties:
        status:
          type: string
          description: the status of the diagnostic report
        observations:
          type: array
          description: optional list of observations to attach to the diagnostic report
          items:
            $ref: '#/components/schemas/CreateObservationRequest'
  securitySchemes:
    OAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.prod.whoop.com/oauth/oauth2/auth
          tokenUrl: https://api.prod.whoop.com/oauth/oauth2/token
          scopes:
            read:recovery: Read Recovery data, including score, heart rate variability, and resting heart rate.
            read:cycles: Read cycles data, including day Strain and average heart rate during a physiological cycle.
            read:workout: Read workout data, including activity Strain and average heart rate.
            read:sleep: Read sleep data, including performance % and duration per sleep stage.
            read:profile: Read profile data, including name and email.
            read:body_measurement: Read body measurements data, including height, weight, and max heart rate.
    Trusted Partner:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.prod.whoop.com/developer/v2/partner/token
          scopes:
            whoop-partner/token: Read service requests and upload results.