Contacts

Search Contacts

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. :::

post/v1/contacts/search

Query parameters

account_idstring required

The Leadfeeder Account ID. The Account ID can be retrieved using the List Accounts endpoint.

page[cursor]string

Cursor for pagination. Use this value to fetch the next page of results.

page[size]integer

The number of items per page. Maximum is 100.

Request body

search_termsstring[]

Search in contact fullname and title fields.

positionsstring[]

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.

emailsstring[]

company_idsstring[]

departmentsstring[]

The departments the contact works in within the company.

hierarchy_levelsstring[]

affiliation'employee' | 'group_employee' | 'related' nullable

Determines how the contact is related to the company.

buyer_persona_idsstring[]

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.

phonesstring[]

Filter contacts by phone number. Each value must be a phone number in E.164 format (e.g. +4972150057501). Returns contacts who have at least one of the supplied phone numbers.

Example request

{
  "search_terms": [
    "John Doe"
  ],
  "positions": [
    "CEO",
    "CTO"
  ],
  "emails": [
    "john.doe@example.com"
  ],
  "company_ids": [
    "129011",
    "159001425"
  ],
  "departments": [
    "marketing_department",
    "students_apprentices"
  ],
  "hierarchy_levels": [
    "top_management",
    "middle_management"
  ],
  "affiliation": "employee",
  "buyer_persona_ids": [
    "7421",
    "7422"
  ],
  "company_locations": [
    {
      "city": "Naples",
      "country_code": "IT"
    },
    {
      "city": "Berlin",
      "country_code": "DE"
    }
  ],
  "phones": [
    "+4972150057501",
    "+4972150057209"
  ]
}

Response

Success

Example response

{
  "data": [
    {
      "type": "contact_summary",
      "id": "435834",
      "attributes": {
        "full_name": "John Doe",
        "gender": "male",
        "hierarchy_level": "employees",
        "meta": {
          "has_phones": true,
          "has_mail": true,
          "has_social_accounts": true
        }
      },
      "relationships": {
        "company": {
          "id": "129011"
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "next_cursor": "dXNlcjpVMEc5V0ZYTlo",
      "total_count": 1450
    },
    "request_id": "cf054205-dd8c-4473-8689-07c30fe0789f"
  }
}

Changes

Changed in 1 of the 15 revisions of this API.22

Aug 15, 2026f31998eea48122See the full diff
- ▲
  removed the enum value unknown_department of the request property departments/items/
  request-property-enum-value-removed
- ▲
  removed the enum value unknown_hierarchy of the request property hierarchy_levels/items/
  request-property-enum-value-removed
- ○
  added subschema #1 subschema #2 to the data response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  removed subschema #1 subschema #2 from the data response property anyOf list for the response status 200
  response-property-any-of-removed

Of the 15 revisions, 1 has no diff computed.

Full history