---
title: "Search Contacts"
method: POST
path: "/v1/contacts/search"
tags: ["Contacts", "v1"]
---

# Search Contacts

`POST /v1/contacts/search`

Search for contacts based on the provided search parameters and returns contact summary objects.
Credit Note: Searches do not consume credits. Credits are only used if you subsequently retrieve deep data for a contact that has not been accessed within the last 12 months.

:::info
Requires the `contacts:read` OAuth2 scope.
:::

## Query parameters

- `account_id` string, required
- `page[cursor]` string
- `page[size]` integer

## Request body

- object
  - `search_terms` string[] — Search in contact fullname and title fields.
  - `positions` string[] — Filter contacts by position. Values are matched as phrases against both the original-language position and its English translation — "Chief" matches "Chief Executive Officer". Multiple values are combined with OR. No typo tolerance — synonyms must be listed explicitly.
  - `emails` string[]
  - `company_ids` string[]
  - `departments` string[] — The departments the contact works in within the company.
  - `hierarchy_levels` string[]
  - `affiliation` 'employee' | 'group_employee' | 'related', nullable — Determines how the contact is related to the company.
  - `buyer_persona_ids` string[] — List of buyer persona IDs to use as a filter. The search will return contacts that match the criteria of at least one of the referenced buyer personas (multiple personas are combined using OR). Buyer persona IDs can be retrieved from the **Retrieve Buyer Personas** endpoint. Unknown or invalid IDs are ignored; if none of the supplied IDs exist or have valid filters, the search returns no results.
  - `company_locations` object[] — Filter contacts by their company's location. Each object can specify a `city`, a `country_code`, or both. Within a single object the conditions are combined with AND; across multiple objects at least one must match (OR). Both fields are matched case-insensitively; the full value must be provided.
    - `city` string
    - `country_code` string
  - `phones` string[] — Filter contacts by phone number. Each value must be a phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164) (e.g. `+4972150057501`). Returns contacts who have at least one of the supplied phone numbers.
  - `filters` object — Filter down search results (combined with AND).
    - `has_phones` boolean
    - `has_email` boolean
    - `has_social_media_profiles` boolean

## Response `200`

Success

- object
  - `data` union, required — Accounts with an active platform subscription receive `ContactSummaryV1` objects, while those without receive `MaskedContactSummaryV1` objects.
    - ContactSummaryV1[]
      - `type` 'contact_summary', required — The type of the object
      - `id` string, required — The Leadfeeder contact ID.
      - `attributes` object, required
        - `full_name` string, required
        - `gender` 'male' | 'female' | 'other' | 'null', nullable, required — The contact's gender.
        - `hierarchy_level` 'employees' | 'top_management' | 'middle_management' | 'unknown_hierarchy' | 'null', nullable, required — The hierarchy level the contact has in the company.
        - `meta` object, required
          - `has_phones` boolean — Indicates if you will get back a landline or mobile phone number with the full contact object.
          - `has_mail` boolean — Indicates if you will get back an email address with the full contact object.
          - `has_social_accounts` boolean — Indicates if you will get back one or more social accounts with the full contact object.
      - `relationships` object, required
        - `company` object, required
          - `id` string, required — The Leadfeeder company ID.
          - `type` 'company_summary', required
    - MaskedContactSummaryV1[]
      - `type` 'masked_contact_summary', required — The type of the object
      - `id` string, required — The Leadfeeder contact ID.
      - `attributes` object, required
        - `full_name` string, required
        - `gender` 'male' | 'female' | 'other' | 'null', nullable, required — The contact's gender.
        - `hierarchy_level` 'employees' | 'top_management' | 'middle_management' | 'unknown_hierarchy' | 'null', nullable, required — The hierarchy level the contact has in the company.
        - `meta` object, required
          - `has_phones` boolean — Indicates if you will get back a landline or mobile phone number with the full contact object.
          - `has_mail` boolean — Indicates if you will get back an email address with the full contact object.
          - `has_social_accounts` boolean — Indicates if you will get back one or more social accounts with the full contact object.
      - `relationships` object, required
        - `company` object, required
          - `id` string, required — The Leadfeeder company ID.
          - `type` 'company_summary', required
  - `meta` object, required
    - `credits` object, required
      - `charged` number, required — How many credits were consumed for this request.
    - `pagination` object, required
      - `next_cursor` string, nullable
      - `total_count` integer, required
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Invalid mandatory fields
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `504` — Server timeout

---

[API](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/9e2e63ba2a4e/schema)