Upcoming Lead Finder API changes

The lead search endpoints in Lead Finder will change on October 22, 2026. The update affects Get search criteria, Get search criteria values, and Search leads.

These changes affect how you build search requests and what the responses contain. Please review the summary below and update your integration in advance to avoid disruption.

Migration checklist

• Replace COUNTRY, CITY, and US_STATE with LOCATION, and COMPANY_COUNTRY and COMPANY_CITY with COMPANY_LOCATION. See removed and replaced criteria.
• Remove GENDER, JOB_TITLE_LEVEL, and JOB_TITLE_ROLE from your search requests. See removed and replaced criteria.
• Send CURRENT_JOB_TITLE and PAST_JOB_TITLE as free text. See job titles as free text.
• Fetch allowed values again for INDUSTRY and COMPANY_TYPE, and verify any values stored in your integration. See new value catalogs.
• Build requests within the operators and max_values returned for each criterion. COMPANY_SIZE and YEARS_OF_EXPERIENCE accept only INCLUDE and one value. See new fields.
• Handle the new validation errors returned by Search leads. See request validation.
• Make sure your integration correctly handles the updated lead data returned by Search leads: uid, linkedin_url, gender, job_title_role, job_title_levels, city, state, and country. See changes in output data.
• Treat 200 OK with an empty leads array as "no results". See no results.

Get search criteria

GET /rest/v2/lead_finder/search_criteria: endpoint documentation

Removed and replaced criteria

After the update, some criteria will be removed, some will be replaced with new ones, and some will change their type. The table below shows what will happen to each current criterion.

Current criterion	Change	Use instead
COUNTRY, CITY, US_STATE	Removed	LOCATION (freetext)
COMPANY_COUNTRY, COMPANY_CITY	Removed	COMPANY_LOCATION (freetext)
GENDER, JOB_TITLE_LEVEL, JOB_TITLE_ROLE	Removed	No replacement
CURRENT_JOB_TITLE, PAST_JOB_TITLE	Type changes from enumerated to freetext	Same criterion
INDUSTRY, COMPANY_TYPE	Still enumerated, with new allowed values	Same criterion
COMPANY_SIZE, YEARS_OF_EXPERIENCE	Still enumerated, with the same allowed values and only INCLUDE and one value accepted	Same criterion
FIRST_NAME, LAST_NAME, COMPANY_NAME, COMPANY_WEBSITE	No change	Same criterion

New fields: operators and max_values

After the update, every criterion will include two new fields:

Field	Type	Description
operators	array[string]	Operators you can use with the criterion
max_values	integer/null	Maximum number of distinct values for one criterion and operator pair. null means no limit

Search leads requests must respect both fields returned for each criterion. Use only the listed operators, and do not send more distinct values than max_values allows. Otherwise, the request will be rejected. See request validation.

Example response with all available criteria:

{
  "search_criteria": {
    "freetext": [
      { "name": "COMPANY_LOCATION", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "COMPANY_NAME", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "COMPANY_WEBSITE", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "CURRENT_JOB_TITLE", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "FIRST_NAME", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "LAST_NAME", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "LOCATION", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "PAST_JOB_TITLE", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 }
    ],
    "enumerated": [
      { "name": "COMPANY_SIZE", "operators": ["INCLUDE"], "max_values": 1 },
      { "name": "COMPANY_TYPE", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "INDUSTRY", "operators": ["INCLUDE", "EXCLUDE"], "max_values": 200 },
      { "name": "YEARS_OF_EXPERIENCE", "operators": ["INCLUDE"], "max_values": 1 }
    ]
  }
}

Get search criteria values

GET /rest/v2/lead_finder/search_criteria/{criterion_name}/values: endpoint documentation

Requests for removed criteria

After the update, a request with a removed criterion as criterion_name will be rejected with 400 Bad Request.

New value catalogs

After the update, the following enumerated criteria will get new sets of allowed values:

• INDUSTRY
• COMPANY_TYPE

Fetch the current values from this endpoint after the update. If you store values for these criteria in your integration, verify them against the new list, because some of them will no longer be accepted.

Search leads

POST /rest/v2/lead_finder/leads: endpoint documentation

Request

Replace removed criteria

After the update, a search request that uses a removed criterion will be rejected with 400 Bad Request.

Use the new equivalents instead:

Before

{ "name": "COUNTRY", "value": "poland", "operator": "EXCLUDE" }

After

{ "name": "LOCATION", "value": "poland", "operator": "EXCLUDE" }

Job titles as free text

After the update, CURRENT_JOB_TITLE and PAST_JOB_TITLE will change from enumerated to freetext. You will no longer need to fetch their values first. Send the job title as text:

{ "name": "CURRENT_JOB_TITLE", "value": "Head of Sales", "operator": "INCLUDE" }

Request validation

After the update, Search leads will reject the whole request with 400 Bad Request if any of the rules below is not met. Search criteria will be validated before credits are charged.

Rule	Example	Error message
The operator must be listed in the criterion's operators	COMPANY_SIZE with EXCLUDE	Unsupported search criterion: name=COMPANY_SIZE, operator=EXCLUDE
The number of distinct values for a criterion and operator pair cannot exceed max_values, and repeated identical values count once	Two COMPANY_SIZE values with INCLUDE	Too many values for search criterion: name=COMPANY_SIZE, operator=INCLUDE, max=1
An enumerated value must exactly match a value from Get search criteria values	INDUSTRY with Software Development instead of software development	Unsupported search criterion value: name=INDUSTRY, operator=INCLUDE, value=Software Development
next_page must be a token issued after the update	A next_page token from a search made before the update	Incorrect search criteria or pagination token

Response

Changes in output data

• uid will use a different format.
• linkedin_url will be returned as a full URL instead of a shortened one, for example https://www.linkedin.com/in/erlich-bachman-404xyz instead of linkedin.com/in/erlich-bachman-404xyz.
• gender, job_title_role, city, state, and country will stay in the response but will always be null. Use location_name for the lead's location.
• job_title_levels will stay in the response but will always be an empty array.

The example below shows only the fields described above.

Before

{
  "gender": "Male",
  "linkedin_url": "linkedin.com/in/erlich-bachman-404xyz",
  "job_title_role": "Operations",
  "job_title_levels": ["Cxo"],
  "location_name": "Palo Alto, California, United States",
  "city": "Palo Alto",
  "state": "California",
  "country": "United States"
}

After

{
  "gender": null,
  "linkedin_url": "https://www.linkedin.com/in/erlich-bachman-404xyz",
  "job_title_role": null,
  "job_title_levels": [],
  "location_name": "Palo Alto, California, United States",
  "city": null,
  "state": null,
  "country": null
}

No results

Currently, when no leads match your search criteria, Search leads returns 404 Not Found. After the update, the same search will return 200 OK with an empty leads array, total_found set to 0, and next_page set to null. If your integration treats 404 Not Found as "no results", update it to check for an empty leads array instead.

Before

{
  "title": "Not Found",
  "status": 404,
  "details": "No records were found matching your search",
  "timestamp": "2025-03-05 17:57:00",
  "extra": null
}

After

{
  "size": 25,
  "leads": [],
  "total_found": 0,
  "next_page": null
}