openapi: 3.0.3
info:
  title: Weave Contacts Phone & Calls API
  description: 'The Weave API is the developer surface of the Weave customer/patient communication and payments platform for small healthcare businesses (dental, optometry, veterinary, medical, and specialty practices). It exposes REST resources across messaging (SMS/text), phone and calls, contacts, scheduling and appointments, payments, digital forms, reviews, and event subscriptions.


    Base URL is https://api.weaveconnect.com. Requests are authenticated with an OAuth 2.0 bearer access token issued by Weave''s OIDC provider (https://oidc.weaveconnect.com, token endpoint under https://auth.weaveconnect.com/oauth2/default) and are scoped to a location (sub-account); the location is identified by a `location_id` query parameter or header on most endpoints.


    Grounding note: the public Weave Developer Portal (https://dp.getweave.com) requires a developer login, so the authoritative request/response schemas could not be read directly. The paths and base URL below are grounded in Weave''s own published Developer Portal client (the app''s compiled configuration and API calls against https://api.weaveconnect.com). Path coverage is therefore high-confidence, while request bodies, query parameters, and response schemas are modeled and should be reconciled against the official reference once portal access is available.'
  version: '1.0'
  contact:
    name: Weave
    url: https://www.getweave.com
  license:
    name: Proprietary
    url: https://www.getweave.com/legal/terms/
servers:
- url: https://api.weaveconnect.com
  description: Weave production API
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Phone & Calls
  description: VoIP call records, recordings, voicemails, and call queues.
paths:
  /v1/call-records:
    get:
      operationId: listCallRecords
      tags:
      - Phone & Calls
      summary: List call records
      description: Lists inbound and outbound call records for a location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of call records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/call-recordings:
    get:
      operationId: listCallRecordings
      tags:
      - Phone & Calls
      summary: List call recordings
      description: Lists available call recordings for a location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: A list of call recordings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallRecording'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/call-recording/signed-url:
    get:
      operationId: getCallRecordingSignedUrl
      tags:
      - Phone & Calls
      summary: Get a call recording signed URL
      description: Returns a short-lived signed URL to download a specific call recording.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      - name: recording_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A signed download URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  expires_at:
                    type: string
                    format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/voicemail-messages:
    get:
      operationId: listVoicemailMessages
      tags:
      - Phone & Calls
      summary: List voicemail messages
      description: Lists voicemail messages for a location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: A list of voicemails.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Voicemail'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/call-queues:
    get:
      operationId: listCallQueues
      tags:
      - Phone & Calls
      summary: List call queues
      description: Lists the call queues configured for a location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: A list of call queues.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/call-queues/metrics:
    get:
      operationId: getCallQueueMetrics
      tags:
      - Phone & Calls
      summary: Get call queue metrics
      description: Returns performance metrics for the location's call queues.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: Call queue metrics.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/department/phone-numbers:
    get:
      operationId: listDepartmentPhoneNumbers
      tags:
      - Phone & Calls
      summary: List department phone numbers
      description: Lists phone numbers assigned to departments within a location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: A list of department phone numbers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        label:
          type: string
    CallRecord:
      type: object
      properties:
        id:
          type: string
          format: uuid
        direction:
          type: string
          enum:
          - inbound
          - outbound
        from:
          type: string
        to:
          type: string
        duration_seconds:
          type: integer
        person_id:
          type: string
        started_at:
          type: string
          format: date-time
    CallRecording:
      type: object
      properties:
        id:
          type: string
          format: uuid
        call_record_id:
          type: string
          format: uuid
        duration_seconds:
          type: integer
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    Voicemail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        from:
          type: string
        duration_seconds:
          type: integer
        viewed:
          type: boolean
        created_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return.
      schema:
        type: integer
        default: 50
    LocationId:
      name: location_id
      in: query
      required: false
      description: The Weave location (sub-account) the request is scoped to. Required on most endpoints; may alternatively be supplied via a location header.
      schema:
        type: string
        format: uuid
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 access token issued by Weave''s OIDC provider. Authorization and token endpoints are served under https://auth.weaveconnect.com/oauth2/default (issuer https://oidc.weaveconnect.com). Present as `Authorization: Bearer ACCESS_TOKEN`.'
      flows:
        authorizationCode:
          authorizationUrl: https://auth.weaveconnect.com/oauth2/default/v1/authorize
          tokenUrl: https://auth.weaveconnect.com/oauth2/default/v1/token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth 2.0 bearer access token passed as `Authorization: Bearer ACCESS_TOKEN`.'