> ## Documentation Index
> Fetch the complete documentation index at: https://openphone-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search contacts

> Search contacts by free text and filters. A contact created or changed moments ago may not appear yet.



## OpenAPI

````yaml https://cdn.quo.com/public-api/openphone-public-api-2026-03-30-dev.json get /contacts/search
openapi: 3.1.0
info:
  title: Quo Public API
  version: 1.0.0
  description: API for connecting with Quo.
  contact:
    name: Quo Support
    email: support@quo.com
    url: https://support.quo.com/
  termsOfService: https://www.quo.com/terms
servers:
  - description: Development server
    url: https://dev-public-api.openphone.dev
security:
  - apiKey: []
tags:
  - description: Operations related to the organization's A2P registration
    name: A2P Registration
  - description: Operations related to calls placed by an AI agent
    name: Agent Calls
  - description: Operations related to text conversations held by an AI agent
    name: Agent Conversations
  - description: Operations related to calls
    name: Calls
  - description: >-
      Operations related to call summaries, including AI-generated summaries and
      Sona voice assistant summaries
    name: Call Summaries
  - description: >-
      Operations related to call transcripts, including AI-generated transcripts
      and Sona voice assistant transcripts
    name: Call Transcripts
  - description: Operations related to contacts
    name: Contacts
  - description: Operations related to contact shares
    name: Contact Shares
  - description: Operations related to contact notes
    name: Contact Notes
  - description: Operations related to contact properties
    name: Contact Properties
  - description: Operations related to conversations
    name: Conversations
  - description: Operations related to workspace invitations
    name: Invites
  - description: Operations related to text messages
    name: Messages
  - description: Operations related to the organization
    name: Organization
  - description: Operations related to phone numbers
    name: Phone Numbers
  - description: Operations related to users
    name: Users
  - description: Operations related to webhooks
    name: Webhooks
  - description: >-
      Operations related to webhook events, including delivery history and test
      events
    name: Webhook Events
paths:
  /contacts/search:
    get:
      tags:
        - Contacts
      summary: Search contacts
      description: >-
        Search contacts by free text and filters. A contact created or changed
        moments ago may not appear yet.
      operationId: searchContacts
      parameters:
        - in: query
          name: query
          required: false
          schema:
            anyOf:
              - type: string
                minLength: 1
                maxLength: 100
                description: >-
                  Free text matched by keyword and by meaning against contact
                  names, companies and phone numbers, such as `query=jane` or
                  `query=0100`. Up to 100 characters, case-insensitive. Leave it
                  out to return the contacts that match the filters.
                examples:
                  - jane
              - type: 'null'
        - in: query
          name: phoneNumber
          required: false
          schema:
            anyOf:
              - anyOf:
                  - type: string
                    description: >-
                      A phone number in E.164 format, including the country
                      code.
                    examples:
                      - '+15555555555'
                    pattern: ^\+[1-9]\d{1,14}$
                  - type: object
                    required:
                      - in
                    properties:
                      in:
                        type: array
                        items:
                          type: string
                          description: >-
                            A phone number in E.164 format, including the
                            country code.
                          examples:
                            - '+15555555555'
                          pattern: ^\+[1-9]\d{1,14}$
                        description: Match contacts with any of these phone numbers.
                        maxItems: 50
                        examples:
                          - +15555555555,+15555555556
                    additionalProperties: false
                description: >-
                  Only return contacts with this exact E.164 phone number, such
                  as `phoneNumber=+15555555555`. To match any of several, use
                  `phoneNumber[in]=+15555555555,+15555555556`. For part of a
                  number, use `query`.
                examples:
                  - '+15555555555'
              - type: 'null'
          style: deepObject
          explode: true
        - in: query
          name: email
          required: false
          schema:
            anyOf:
              - anyOf:
                  - type: string
                    examples:
                      - jane@example.com
                    format: email
                  - type: object
                    required:
                      - in
                    properties:
                      in:
                        type: array
                        items:
                          type: string
                          format: email
                        description: Match contacts with any of these email addresses.
                        maxItems: 50
                        examples:
                          - jane@example.com,john@example.com
                    additionalProperties: false
                description: >-
                  Only return contacts with this exact email address, such as
                  `email=jane@example.com`. To match any of several, use
                  `email[in]=jane@example.com,john@example.com`.
                examples:
                  - jane@example.com
              - type: 'null'
          style: deepObject
          explode: true
        - in: query
          name: company
          required: false
          schema:
            anyOf:
              - anyOf:
                  - type: string
                    minLength: 1
                    examples:
                      - Acme
                  - type: object
                    required:
                      - in
                    properties:
                      in:
                        type: array
                        items:
                          type: string
                          minLength: 1
                        description: Match contacts at any of these companies.
                        maxItems: 50
                        examples:
                          - Acme,Globex
                    additionalProperties: false
                description: >-
                  Only return contacts at this company, matched exactly,
                  including capitalization, such as `company=Acme` (it does not
                  match `Acme Inc` or `ACME`). To match any of several, use
                  `company[in]=Acme,Globex`. To match a company name loosely,
                  put it in `query`.
                examples:
                  - Acme
              - type: 'null'
          style: deepObject
          explode: true
        - in: query
          name: source
          required: false
          schema:
            anyOf:
              - anyOf:
                  - type: string
                    minLength: 1
                    examples:
                      - openphone-hubspot
                  - type: object
                    required:
                      - in
                    properties:
                      in:
                        type: array
                        items:
                          type: string
                          minLength: 1
                        description: Match contacts carrying any of these source labels.
                        maxItems: 50
                        examples:
                          - openphone-hubspot,openphone-salesforce
                    additionalProperties: false
                description: >-
                  Filter by source label, such as `source=openphone-hubspot`. To
                  match any of several, use
                  `source[in]=openphone-hubspot,openphone-salesforce`.
                examples:
                  - openphone-hubspot
              - type: 'null'
          style: deepObject
          explode: true
        - in: query
          name: createdAt
          required: false
          schema:
            anyOf:
              - type: object
                properties:
                  gte:
                    description: >-
                      Only return contacts created at or after this timestamp.
                      The bound is inclusive.
                    examples:
                      - '2022-01-01T00:00:00Z'
                    type: string
                    format: date-time
                  lte:
                    description: >-
                      Only return contacts created at or before this timestamp.
                      The bound is inclusive.
                    examples:
                      - '2022-01-01T00:00:00Z'
                    type: string
                    format: date-time
                additionalProperties: false
                description: >-
                  Bound the results by creation time, in ISO 8601 format:
                  `createdAt[gte]=2022-01-01T00:00:00Z&createdAt[lte]=2022-02-01T00:00:00Z`.
                  Both bounds are inclusive.
                examples:
                  - gte: '2022-01-01T00:00:00Z'
              - type: 'null'
          style: deepObject
          explode: true
        - in: query
          name: limit
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 50
                maximum: 50
                default: 50
                description: >-
                  Page size. Search returns at most 50 contacts, the only value
                  accepted.
              - type: 'null'
        - in: header
          name: Quo-Api-Version
          required: true
          schema:
            type: string
            enum:
              - '2026-03-30'
            description: 'API version header. Supported values: 2026-03-30'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - nextCursor
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - createdAt
                        - updatedAt
                        - actorId
                      properties:
                        id:
                          description: The ID of the contact.
                          examples:
                            - 6a145ff26212a192852c856e
                          example: 6a145ff26212a192852c856e
                          type: string
                          pattern: ^(.*)$
                        externalId:
                          anyOf:
                            - type: string
                              description: The external ID of the contact.
                              examples:
                                - '1234567890'
                              example: '1234567890'
                            - type: 'null'
                        source:
                          anyOf:
                            - type: string
                              description: The source of the contact.
                              examples:
                                - public-api
                              example: public-api
                            - type: 'null'
                        sourceUrl:
                          anyOf:
                            - type: string
                              description: A link to the contact in the source system.
                              format: uri
                              examples:
                                - https://example.com/contacts/001
                              minLength: 1
                              maxLength: 200
                              example: https://example.com/contacts/001
                            - type: 'null'
                        firstName:
                          anyOf:
                            - type: string
                              description: The first name of the contact.
                              examples:
                                - John
                              example: John
                            - type: 'null'
                        lastName:
                          anyOf:
                            - type: string
                              description: The last name of the contact.
                              examples:
                                - Doe
                              example: Doe
                            - type: 'null'
                        company:
                          anyOf:
                            - type: string
                              description: The company of the contact.
                              examples:
                                - Quo
                              example: Quo
                            - type: 'null'
                        role:
                          anyOf:
                            - type: string
                              description: The role of the contact.
                              examples:
                                - admin
                              example: admin
                            - type: 'null'
                        createdAt:
                          description: The timestamp of the contact creation.
                          examples:
                            - '2021-01-01T00:00:00Z'
                          example: '2021-01-01T00:00:00Z'
                          type: string
                          format: date-time
                        updatedAt:
                          description: The timestamp of the contact update.
                          examples:
                            - '2021-01-01T00:00:00Z'
                          example: '2021-01-01T00:00:00Z'
                          type: string
                          format: date-time
                        actorId:
                          description: The actor ID of the contact.
                          examples:
                            - US123abc
                          example: US123abc
                          anyOf:
                            - type: string
                              pattern: ^US(.*)$
                            - type: string
                              pattern: ^SYU(.*)$
                  nextCursor:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Cursor for the next page, or null when there are no more
                      pages.
                    examples:
                      - eyJsYXN0SWQiOiJVU211a09NaXBhIn0
                    example: eyJsYXN0SWQiOiJVU211a09NaXBhIn0
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - docs
                  - title
                properties:
                  message:
                    type: string
                  docs:
                    type: string
                    const: https://quo.com/docs
                  title:
                    type: string
                    const: Bad Request
                  trace:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                        - path
                        - message
                        - schema
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                        value: {}
                        schema:
                          type: object
                          properties:
                            type:
                              type: string
              example:
                message: The input was invalid
                docs: https://quo.com/docs
                title: Bad Request
                trace: '6897907457496870895'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - docs
                  - title
                properties:
                  message:
                    type: string
                  docs:
                    type: string
                    const: https://quo.com/docs
                  title:
                    type: string
                    const: Unauthorized
                  trace:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                        - path
                        - message
                        - schema
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                        value: {}
                        schema:
                          type: object
                          properties:
                            type:
                              type: string
              example:
                message: User is unauthorized to perform this action
                docs: https://quo.com/docs
                title: Unauthorized
                trace: '6897907457496870895'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - docs
                  - title
                properties:
                  message:
                    type: string
                  docs:
                    type: string
                    const: https://quo.com/docs
                  title:
                    type: string
                    const: Forbidden
                  trace:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                        - path
                        - message
                        - schema
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                        value: {}
                        schema:
                          type: object
                          properties:
                            type:
                              type: string
              example:
                message: User is forbidden to perform this action
                docs: https://quo.com/docs
                title: Forbidden
                trace: '6897907457496870895'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - docs
                  - title
                properties:
                  message:
                    type: string
                  docs:
                    type: string
                    const: https://quo.com/docs
                  title:
                    type: string
                    const: Not Found
                  trace:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                        - path
                        - message
                        - schema
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                        value: {}
                        schema:
                          type: object
                          properties:
                            type:
                              type: string
              example:
                message: The contact was not found
                docs: https://quo.com/docs
                title: Not Found
                trace: '6897907457496870895'
        '500':
          description: Unexpected Error | Unknown Error
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UnexpectedError'
                  - $ref: '#/components/schemas/UnknownError'
              examples:
                UnexpectedError:
                  summary: Unexpected Error
                  value:
                    message: An unexpected error has occurred
                    docs: https://quo.com/docs
                    title: Unexpected Error
                    trace: '6897907457496870895'
                UnknownError:
                  summary: Unknown Error
                  value:
                    message: An unknown error has occurred
                    docs: https://quo.com/docs
                    title: Unknown Error
                    trace: '6897907457496870895'
      security:
        - apiKey: []
components:
  schemas:
    UnexpectedError:
      type: object
      required:
        - message
        - docs
        - title
      properties:
        message:
          type: string
        docs:
          type: string
          const: https://quo.com/docs
        title:
          type: string
          const: Unexpected
        trace:
          type: string
        errors:
          type: array
          items:
            type: object
            required:
              - path
              - message
              - schema
            properties:
              path:
                type: string
              message:
                type: string
              value: {}
              schema:
                type: object
                properties:
                  type:
                    type: string
      title: Unexpected Error
    UnknownError:
      type: object
      required:
        - message
        - docs
        - title
      properties:
        message:
          type: string
        docs:
          type: string
          const: https://quo.com/docs
        title:
          type: string
          const: Unknown
        trace:
          type: string
        errors:
          type: array
          items:
            type: object
            required:
              - path
              - message
              - schema
            properties:
              path:
                type: string
              message:
                type: string
              value: {}
              schema:
                type: object
                properties:
                  type:
                    type: string
      title: Unknown Error
  securitySchemes:
    apiKey:
      in: header
      name: Authorization
      type: apiKey

````