> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveinspect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List contacts

<Note>
  **The Hive Inspect API is a work in progress.** It is available to a small group of accounts today, and the release for everyone is coming very soon.
</Note>


## OpenAPI

````yaml /api/openapi.json get /v1/contacts
openapi: 3.1.0
info:
  title: Hive Inspect API
  version: 1.0.0
  description: Connect other tools to your Hive Inspect contacts, inspections and events.
servers:
  - url: https://api.hiveinspect.com
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Agents, clients and every other contact in your organization.
  - name: Agencies
    description: The brokerages your agents belong to. Read-only.
  - name: Inspections
    description: Read-only access to your inspections.
  - name: Attachments
    description: Additional reports and additional documents on an inspection.
  - name: Events
    description: Extra appointments on an inspection, such as a radon drop-off or pick-up.
paths:
  /v1/contacts:
    get:
      tags:
        - Contacts
      summary: List contacts
      operationId: listContacts
      parameters:
        - name: ids
          in: query
          required: false
          description: Comma-separated contact ids (up to 200) to fetch in one call
          schema:
            type: string
        - name: role
          in: query
          required: false
          description: >-
            Only contacts who have had this role on an inspection: `agent`
            (Buyer Agent or Listing Agent), `client` (Customer), or an exact
            role: Customer, Buyer Agent, Listing Agent, Sub Contractor,
            Insurance Agent, Lender, Builder, Transaction Coordinator, Attorney,
            Title Company, Others
          schema:
            type: string
        - name: tag_id
          in: query
          required: false
          description: Only contacts with this tag
          schema:
            type: string
        - name: tag
          in: query
          required: false
          description: >-
            Only contacts with any of these tag names (case-insensitive); repeat
            for several
          schema:
            type: array
            items:
              type: string
        - name: agency_id
          in: query
          required: false
          description: Only contacts linked to this agency (see /v1/agencies)
          schema:
            type: string
            format: uuid
        - name: email
          in: query
          required: false
          description: Exact email match (case-insensitive)
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Name, email, or phone (3+ digits) contains
          schema:
            type: string
        - name: updated_since
          in: query
          required: false
          description: >-
            ISO 8601 date or timestamp; contacts created or changed at/after
            this time
          schema:
            type: string
        - name: sort
          in: query
          required: false
          description: >-
            first_name, last_name, agency_name, created_at or updated_at; prefix
            '-' for descending (default: by id)
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          description: '`next_cursor` from the previous page'
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1-200 (default 50)
          schema:
            type: integer
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '400':
          description: Invalid parameter
        '401':
          description: Missing, invalid or inactive API key
        '429':
          description: Rate limit exceeded (120 requests/minute per key owner)
components:
  schemas:
    ContactList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        next_cursor:
          type:
            - string
            - 'null'
        total:
          type: integer
          description: Every record matching the filters, across all pages
      example:
        data:
          - id: 0b6f2c1e-7d1a-4c55-9a5e-2f3b8c1d4e6f
            first_name: Dana
            last_name: Reyes
            email: dana@example.com
            cc_email: null
            phone: (512) 555-0142
            business_name: null
            agency_name: Lone Star Realty
            agency_id: 6c5b4a39-2817-4f6e-9d0c-8b7a6f5e4d3c
            agency:
              id: 6c5b4a39-2817-4f6e-9d0c-8b7a6f5e4d3c
              name: Lone Star Realty
              phone: (512) 555-0100
              website: https://lonestarrealty.example.com
            uses_agency_address: true
            address: 410 Oak St
            address_line2: null
            city: Austin
            state: TX
            zip: '78701'
            country: US
            birthday: '1988-04-12'
            website: null
            social: null
            notes: Prefers text messages
            photo_url: https://files.example.com/signed-link-valid-for-1-hour
            tags:
              - id: 5a1d9c3e-2b7f-4f0a-8c6d-1e2f3a4b5c6d
                name: Top agent
            roles:
              - Buyer Agent
              - Listing Agent
            created_at: '2026-03-02T15:04:11Z'
            updated_at: '2026-09-18T20:41:07Z'
        next_cursor: 0b6f2c1e-7d1a-4c55-9a5e-2f3b8c1d4e6f
        total: 1
    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type:
            - string
            - 'null'
        email:
          type: string
          format: email
        cc_email:
          type:
            - string
            - 'null'
          format: email
        phone:
          type:
            - string
            - 'null'
        business_name:
          type:
            - string
            - 'null'
        agency_name:
          type:
            - string
            - 'null'
        address:
          type:
            - string
            - 'null'
        address_line2:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        zip:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
          description: ISO-2, e.g. US or CA
        birthday:
          type:
            - string
            - 'null'
          format: date
        website:
          type:
            - string
            - 'null'
        social:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
        notes:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
        roles:
          type: array
          items:
            type: string
          description: Distinct roles this contact has had on inspections
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        photo_url:
          type:
            - string
            - 'null'
          description: Signed link, valid for 1 hour
        agency_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The agency (brokerage) this contact is linked to, from /v1/agencies.
            Null when agency_name is plain text.
        uses_agency_address:
          type: boolean
          description: 'true: the contact''s address follows the agency''s address'
        agency:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
                  format: uuid
                name:
                  type:
                    - string
                    - 'null'
                phone:
                  type:
                    - string
                    - 'null'
                website:
                  type:
                    - string
                    - 'null'
            - type: 'null'
          description: The linked agency, when there is one
      example:
        id: 0b6f2c1e-7d1a-4c55-9a5e-2f3b8c1d4e6f
        first_name: Dana
        last_name: Reyes
        email: dana@example.com
        cc_email: null
        phone: (512) 555-0142
        business_name: null
        agency_name: Lone Star Realty
        agency_id: 6c5b4a39-2817-4f6e-9d0c-8b7a6f5e4d3c
        agency:
          id: 6c5b4a39-2817-4f6e-9d0c-8b7a6f5e4d3c
          name: Lone Star Realty
          phone: (512) 555-0100
          website: https://lonestarrealty.example.com
        uses_agency_address: true
        address: 410 Oak St
        address_line2: null
        city: Austin
        state: TX
        zip: '78701'
        country: US
        birthday: '1988-04-12'
        website: null
        social: null
        notes: Prefers text messages
        photo_url: https://files.example.com/signed-link-valid-for-1-hour
        tags:
          - id: 5a1d9c3e-2b7f-4f0a-8c6d-1e2f3a4b5c6d
            name: Top agent
        roles:
          - Buyer Agent
          - Listing Agent
        created_at: '2026-03-02T15:04:11Z'
        updated_at: '2026-09-18T20:41:07Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key from Business Tools → API Access.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.