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

# Search for contacts

Retrieves a list of contacts that match the provided query string. The search behavior depends on whether the query contains an "@" symbol: if present, it searches by email only; otherwise, it searches both name and email fields. Only trusted contacts (session\_uuid is null) are returned in the results.


## OpenAPI

````yaml https://api.getfernand.com/openapi.json get /contacts
openapi: 3.0.3
info:
  title: Fernand API Documentation
  version: '3.0'
  description: This is the documentation for the [Fernand](https://getfernand.com) API.
  termsOfService: https://getfernand.com/terms
  contact:
    name: Fernand Support
    url: https://getfernand.com
    email: support@getfernand.com
  x-logo:
    url: https://app.getfernand.com/images/favicon/icon_128.png
servers:
  - url: https://api.getfernand.com
    description: ''
    x-last-modified: 1764750693905
security:
  - apiKeyHeader: []
externalDocs:
  description: You can access our documentation online by visiting https://api.fernand.help
  url: https://api.fernand.help
paths:
  /contacts:
    get:
      tags:
        - Contacts
      summary: Search for contacts
      description: >-
        Retrieves a list of contacts that match the provided query string. The
        search behavior depends on whether the query contains an "@" symbol: if
        present, it searches by email only; otherwise, it searches both name and
        email fields. Only trusted contacts (session_uuid is null) are returned
        in the results.
      operationId: searchContacts
      parameters:
        - name: query
          in: query
          required: false
          schema:
            type: string
          description: >-
            Search query string. If contains "@", searches email only. Otherwise
            searches both name and email.
          example: richard
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
            maximum: 99
            minimum: 1
          description: Maximum number of contacts to return.
      responses:
        '200':
          description: List of contacts matching the search query.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
        '400':
          description: Invalid limit parameter (must be between 1 and 99).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the contact
          example: 12345
        name:
          type: string
          maxLength: 250
          nullable: true
          description: >-
            Display name of the contact, can be set locally or derived from
            various sources. Returns local_name if set, otherwise the name
            field, or generates a name from the email address.
          example: Richard Hendricks
        firstname:
          type: string
          nullable: true
          description: First name extracted from the contact's full name
          example: Richard
        email:
          type: string
          maxLength: 250
          description: >-
            Email address of the contact, stored in lowercase and decoded from
            punycode if applicable
          example: richard.hendricks@piedpiper.com
        avatar:
          type: string
          format: uri
          description: >-
            URL to the contact's avatar image, fetched from Gravatar or domain
            favicon
          example: >-
            https://api.getfernand.com/contacts/richard.hendricks@piedpiper.com/avatar
        company:
          type: object
          nullable: true
          description: Company information associated with the contact's email domain
          properties:
            id:
              type: integer
              format: int64
              description: Company unique identifier
              example: 123
            name:
              type: string
              description: Company name
              example: PiedPiper
            domain:
              type: string
              description: Company domain
              example: piedpiper.com
            logo:
              type: string
              format: uri
              description: Company logo URL, provided by Fetchlab.net
              example: https://api.fetchlab.net/icons/piedpiper.com
            url:
              type: string
              format: uri
              description: Company website URL
              example: https://piedpiper.com
        is_role:
          type: boolean
          description: >-
            Indicates if the email is a role-based address (e.g., support@,
            info@, contact@)
          example: false
        is_trusted:
          type: boolean
          description: >-
            Indicates if the contact is trusted (Untrusted contacts come from
            unverified live chat sessions).
          example: true
        subscription_status:
          type: string
          nullable: true
          enum:
            - active
            - past_due
            - unpaid
            - canceled
            - churned
            - incomplete
            - trialing
          description: >-
            Current subscription status from payment processor, only available
            when complete serialization is requested
          example: active
        subscription_start:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp when the subscription started (UTC), only available when
            complete serialization is requested
          example: '2024-01-15T10:30:00Z'
        financials:
          type: object
          nullable: true
          description: >-
            Financial information including payment sources, subscriptions, and
            payment history, only available when complete serialization is
            requested
          properties:
            sources:
              type: object
              description: >-
                Payment processor sources (Stripe, Paddle, Lemon Squeezy) with
                customer information
            subscriptions:
              type: object
              properties:
                total:
                  type: integer
                  description: Total number of subscriptions
                latest:
                  type: object
                  nullable: true
                  description: Latest subscription details
            payments:
              type: object
              properties:
                total:
                  type: integer
                  description: Total number of payments
                data:
                  type: array
                  description: Latest 5 payments
                  items:
                    type: object
      required:
        - id
        - email
      x-computed-hash: 5a3ac876cb3cfdd7545e5e793f2eda98e10d4b4e76f789c690533ff39c29cd1f
      x-last-modified: 1769075324
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      description: >-
        Authenticate your account by including your secret key in API requests.

        You can manage your API keys in the
        [Dashboard](https://app.getfernand.com/).


        Authentication to the API is performed by using the HTTP Header
        X-API-Key.
      name: X-API-Key
      in: header
      x-last-modified: 1764750344730

````