openapi: 3.0.3
info:
  title: Weave Contacts Messaging 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: Messaging
  description: Two-way SMS/text messaging with patients.
paths:
  /v1/messages:
    get:
      operationId: listMessages
      tags:
      - Messaging
      summary: List messages
      description: Lists SMS/text messages for a location, most recent first.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      - name: person_id
        in: query
        required: false
        description: Filter to messages exchanged with a specific contact.
        schema:
          type: string
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: sendMessage
      tags:
      - Messaging
      summary: Send a message
      description: Sends an SMS/text message from the location to a patient.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageInput'
      responses:
        '200':
          description: The sent message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/chart-messages:
    get:
      operationId: listChartMessages
      tags:
      - Messaging
      summary: List chart-thread messages
      description: Lists messages within a patient chart/message thread.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      - name: person_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of chart messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/account/bulk-message-quota:
    get:
      operationId: getBulkMessageQuota
      tags:
      - Messaging
      summary: Get bulk-message quota
      description: Returns the remaining bulk (mass-text) message quota for the account.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: Bulk message quota.
          content:
            application/json:
              schema:
                type: object
                properties:
                  quota:
                    type: integer
                  used:
                    type: integer
                  remaining:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/sms-phone-numbers:
    get:
      operationId: listSmsPhoneNumbers
      tags:
      - Messaging
      summary: List SMS phone numbers
      description: Lists the SMS-capable phone numbers configured for the location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: A list of SMS phone numbers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/quick-fill/message/send:
    post:
      operationId: sendQuickFillMessage
      tags:
      - Messaging
      summary: Send a Quick Fill message
      description: Texts an open-appointment (Quick Fill) offer to one or more contacts to fill a newly available slot.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                person_ids:
                  type: array
                  items:
                    type: string
                body:
                  type: string
      responses:
        '200':
          description: Quick Fill send result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/quick-fill/message/history:
    get:
      operationId: getQuickFillMessageHistory
      tags:
      - Messaging
      summary: Get Quick Fill message history
      description: Returns the history of Quick Fill messages sent from the location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: Quick Fill message history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        label:
          type: string
    MessageInput:
      type: object
      required:
      - person_id
      - body
      properties:
        person_id:
          type: string
        body:
          type: string
        media_urls:
          type: array
          items:
            type: string
            format: uri
    Message:
      type: object
      properties:
        id:
          type: string
          format: uuid
        location_id:
          type: string
          format: uuid
        person_id:
          type: string
          format: uuid
        direction:
          type: string
          enum:
          - inbound
          - outbound
        body:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      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`.'