openapi: 3.0.3
info:
  title: Weave Contacts 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: Contacts
  description: Patient/customer contacts and contact info.
paths:
  /v1/contacts:
    get:
      operationId: listContacts
      tags:
      - Contacts
      summary: List contacts
      description: Lists the contacts (patients/customers) for a location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/contacts/search:
    post:
      operationId: searchContacts
      tags:
      - Contacts
      summary: Search contacts
      description: Searches contacts by name, phone, email, or other attributes.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
      responses:
        '200':
          description: Matching contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/contact-infos:
    get:
      operationId: listContactInfos
      tags:
      - Contacts
      summary: List contact info records
      description: Lists contact-info records (phone numbers, emails) for a location's contacts.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: A list of contact info records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/contacts/block:
    post:
      operationId: blockContact
      tags:
      - Contacts
      summary: Block a contact
      description: Blocks a contact from receiving messages from the location.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                person_id:
                  type: string
      responses:
        '200':
          description: Block confirmation.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/contacts/unblock:
    post:
      operationId: unblockContact
      tags:
      - Contacts
      summary: Unblock a contact
      description: Unblocks a previously blocked contact.
      parameters:
      - $ref: '#/components/parameters/LocationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                person_id:
                  type: string
      responses:
        '200':
          description: Unblock confirmation.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      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
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        mobile_phone:
          type: string
        email:
          type: string
          format: email
        blocked:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  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`.'