Surfe API
Get API KeySupportGive feedback

Changelog

Changes to the Surfe API

October 2nd, 2026

  • Revenue ranges returned through the endpoint GET /v1/people/search/filters have been updated:
    • Company revenue (in USD) is now split into finer ranges above 100M: 0-1M, 1-10M, 10-50M, 50-100M, 100-250M, 250-500M, 500-1000M, 1-10B, 10-100B and >100B.

September 30th, 2026

  • A new hiring signal is available for companies: the job postings a company currently has open.
    • POST /v2/companies/search can filter by hiring with the new filters.hiring object: minActivePostings (the company's total open postings) and departments (at least one open posting in any of them). When both are set, a company must match both. Departments take the values listed in departments; any other value returns 400 with input_validation_failed.
    • Each company in the search results includes a hiring summary with activePostings.
    • GET /v2/companies/enrich/:id results and the company.enrichment.completed webhook now include signals.hiring with activePostings, newPostingsLast30Days and the open postings per department. The signal is absent when we hold no job postings data for the company.
  • In GET /v2/companies/enrich/:id results and the company.enrichment.completed webhook, signals.leadershipChange and signals.funding are now absent when there is no data for this company. They were previously returned as null.

September 29th, 2026

  • A new funding signal is available for companies: the funding rounds a company raised in the last 12 months.
    • POST /v2/companies/search can filter by funding with the new filters.funding object: minTotalRaised and maxTotalRaised (in USD), minRounds and fundedSince (YYYY-MM-DD).
    • Each company in the search results includes a funding summary with rounds, totalRaised and latestRoundDate.
    • GET /v2/companies/enrich/:id results and the company.enrichment.completed webhook now include signals.funding with rounds, totalRaised and the fundingRounds themselves, most recent first.
    • The top-level fundingRounds field of those results and the webhook has been removed. The rounds are now in signals.funding.fundingRounds.

September 28th, 2026

  • POST /v2/people/search uses a new seniority classification:
    • The people.seniorities filter accepts the new values Founder / Owner, C-Level, Vice President (VP), Director, Head, Manager, Senior Individual Contributor, Entry-Level and Other. See the seniorities.
    • The seniorities of each person in the results holds their seniority from the new classification: a single value, or an empty list when we have no seniority for the person.
    • The values Board Member, Founder, Owner, Partner and VP are deprecated. They are still accepted: Board Member is searched as C-Level, Founder, Owner and Partner as Founder / Owner, and VP as Vice President (VP).
    • C-Level, Director, Head, Manager and Other keep their names, but people are classified differently, so the same filter can return different people.
  • The seniorities list returned by GET /v1/people/search/filters contains the new values.

September 24th, 2026

  • POST /v2/people/enrich accepts a new optional enrichmentOptions.timeoutSeconds field (1 to 600).
    • It caps how long the enrichment of each person may take. Once the limit is reached, providers that have not started are skipped, providers still running are stopped, and the results found so far are returned.
    • The limit applies to each person separately, not to the whole request. Lower values return results faster at the cost of a lower find rate. When unset, system defaults apply.

September 22th, 2026

  • A new leadership change signal is available for companies: director-level and more senior roles that changed hands through a new hire, a promotion or a departure.
    • POST /v2/companies/search results now include a summary of each company's leadership changes: how many there are, when the latest one happened and what kind it was. You can also filter the search by a change's kind and by how recent it is.
    • GET /v2/companies/enrich/:id results and the company.enrichment.completed webhook now include a company's leadership changes: how many there are and the ten most recent ones. The signal is null when we hold no leadership change data for the company.
    • The new POST /v2/companies/signals/leadership-change endpoint returns a company's full list of changes.

September 11th, 2026

  • POST /v2/companies/search can now filter companies by recent leadership changes:
    • New filters.leadershipChange object with types (one or more of new_hire, promotion, departure) and changedSince (YYYY-MM-DD). Send at least one of the two; an empty object is ignored.
    • Each company in the results includes a leadershipChange summary with changeCount, latestDate and latestTypes. The field is absent when we have no leadership change data for the company.
  • POST /v2/companies/search now validates the technology filters:
    • technologies, technologiesExcluded, technologyCategories and technologyCategoriesExcluded only accept the values listed in technologies. The values are case-sensitive.
    • Technology names keep their brand casing (for example HubSpot). Technology categories are lowercase (for example customer relationship management).
    • A request with a value that is not in the list returns 400 with input_validation_failed. The response names the field and the rejected value. Such a request previously returned 200 with an empty result.
    • The same technology filters under companies in POST /v2/people/search behave the same way.
  • POST /v2/people/search now supports the hierarchical Department taxonomy:
    • New people.departmentClassifications and people.departmentClassificationsExcluded filters. Each entry names one department and, optionally, its sub-departments. See the department and sub-department codes.
    • Each person in the results includes a new departmentClassifications array, in the same shape as the filter.
    • The people.departments filter and response field are now deprecated. They keep the same values and behavior. Do not combine them with the new filters in one request.

September 9th, 2026

  • The accepted values for the technologies, technologiesExcluded, technologyCategories and technologyCategoriesExcluded filters of POST /v2/companies/search were refreshed:

August 17th, 2026

  • Credits & Quotas corrections:
    • People enrichment daily quota corrected to 50,000 profiles per day. The page previously listed 2,000 per day, which had been the value until the quota was raised in June 2025.
    • People enrichment hourly and per-minute caps documented: 20,000 profiles per hour and 10,000 profiles per minute, applied on top of the daily quota.
    • Reset behaviour clarified: daily quotas reset at midnight in the user's local time, while the hourly and per-minute caps reset on each clock hour and clock minute (UTC).

July 31st, 2026

  • POST /v2/people/search documentation correction:
    • The response example for the country field now shows a lowercase ISO 3166-1 alpha-2 country code (for example fr) instead of a full country name. This is the format the endpoint has always returned, and the same format the countries filters accept.
    • 📝 Note: This is a documentation fix only. The API response has not changed, so no action is required.

July 1st, 2026

June 30th, 2026

  • People per company limit updated for the endpoint POST /v2/people/search
    • The maximum limit for the field peoplePerOrganization has been increased to 40.

June 26th, 2026

  • Credits & Quotas clarifications:
    • Search credits section expanded to cover all supported endpoints: people search, company search, company enrichment, and reverse email enrichment.
    • Quotas table updated to show free vs. search credit limits side by side.
    • People enrichment credits section updated to reflect cascade-based pricing — see Enrich people for details.

June 25th, 2026

June 22nd, 2026

  • New company and people filters were added to the endpoints POST /v2/people/search and POST /v2/companies/search
    • A new flag isExcluded was added to the localities filter for companies. When set to true the localities filters are used to exclude results.
    • Two new people filters called countriesExcluded and statesExcluded. These filters allow excluding specific countries or regions.

June 19th, 2026

  • The limits for country filters has been increased from 100 to 250 for the following endpoints:
    • The filters companies.countries, companies.localities.countries and people.countries from the endpoint POST /v2/people/search.
    • The filters filters.countries and filterslocalities.countries from the endpoint POST /v2/companies/search.

June 19th, 2026

  • Personal email enrichment is now available via a new cascade:
    • POST /v2/people/enrich: set acceptedEmailType to personal to trigger the personal email cascade. Personal emails are priced separately, check endpoint documentation for more details.

June 16th, 2026

June 9th, 2026

June 8th, 2026

  • POST /v2/people/enrich: the include.jobHistory and include.linkedInUrl flag is now available to all accounts — no special configuration required.
  • POST /v2/people/search now returns 402 when the account does not have enough search credits.

June 4th, 2026

  • Credits & Quotas updated:
    • Organization search quota clarified: 200 searches per day by default, or up to 100,000 per day when using search credits.
    • POST /v2/companies/search now deducts ⌈results / 25⌉ ICP search credits per call when credit charging is enabled, and returns 402 when credits are insufficient. Contact api.support@surfe.com to request search credits.

May 28th, 2026

  • New MCP Server page documenting how to connect AI assistants (Claude Desktop, Cursor, Windsurf, etc.) to Surfe via the Model Context Protocol. Covers the connection URL, Claude Desktop quickstart, and example prompts.

May 26th, 2026

  • New enrichmentOptions field added to POST /v2/people/enrich request body. Allows specifying enrichment source and whether to skip mobile enrichment when no email is found (skipMobileEnrichmentIfNoEmailFound).
  • New organizationIDMappings field added to POST /v2/people/search request body. Maps organization domains to external IDs — results from matching organizations will include the mapped ID in the externalID response field.
  • New externalID field in POST /v2/people/search response.

May 11th, 2026

May 4th, 2026

  • One Company filter was deprecated from the endpoints POST /v2/people/search and POST /v2/companies/search
    • The countries filter has been deprecated, you should use the new localities filter which allows for more in depth location searches.
    • 📝 Note: This deprecation is non-breaking — existing API integrations using the countries filter will continue to work as before.
  • 13 new company filters were added to POST /v2/people/search and POST /v2/companies/search
    • The naicsCodes and naicsCodesExcluded filters allow searching by NAICS industry codes.
    • The names filter allow searching by Company names.
    • The industriesExcluded filter allows excluding specific industries.
    • The technologies, technologiesExcluded, technologyCategories, and technologyCategoriesExcluded filters allow searching by different technologies and their categories.
    • The departmentSizes filter allows search by a specific department within a specific range of employees.
    • The keywords, and keywordsExcluded filters allow searching by specific keywords.
    • The yearFounded filter allows search for companies founded within a specific time range.
    • The localities filter allows searching for companies by one or more of the following:
      • Countries and world regions.
      • Specific regions within a country.
      • Specific zip codes.
      • Free text within a company's full address.
      • Any locality filter can be set to target HQ locations only or any location.

April 29th, 2026

  • 5 new ICP peoples filters were added for filters to POST /v2/recommendations/icp and GET /v2/recommendations/icp
    • The states filter allows searching with a specific region within a country.
    • The exactJobTitles filter allows searching by exact job titles without expanding to similar job titles.
    • The previousCompanyDomains filter allows searching by a person's previous companies.
    • The jobChangePeriodInDays filter allows searching for people who have recently changed jobs.
    • The excludeDepartments filters out people who are not in the list of excluded departments.
  • 13 new ICP company filters were added for filters to POST /v2/recommendations/icp and GET /v2/recommendations/icp
    • The departmentSizes filter allows searching for companies having departments of a certain employee size.
    • The employeeCounts filter allows searching for companies having multiple non-consecutive employees quantities.
    • The revenues filter allows searching for companies having multiple non-consecutive revenues amounts.
    • The excludeDomains filter filters out companies with the listed excluded domains.
    • The excludeIndustries filter filters out companies with the listed excluded industries.
    • The excludeTechnologies filter filters out companies with the listed excluded technologies.
    • The includeDomains filter allows searching for companies having the specified domains.
    • The localities filter searching for companies having primary or non-primary offices in the specified countries or states.
    • The locations filter allows searching for companies having non-primary offices in the specified countries.
    • The states filter allows searching for companies having non-primary offices in the specified states.
    • The technologies filter allows searching for companies working with the specified technologies.
    • The yearFounded filter allows searching for companies founded in the specified years interval.
    • The zipCodes filter allows searching for companies having non-primary offices in the specified zip-code areas.

April 29th, 2026

  • 4 new people filters were added to POST /v2/people/search
    • The states filter allows searching with a specific region within a country.
    • The exactJobTitles filter allows searching by exact job titles without expanding to similar job titles.
    • The previousCompanyDomains filter allows searching by a person's previous companies.
    • The jobChangePeriodInDays filter allows searching for people who have recently changed jobs.

April 21st, 2026

  • New batch.enrichment.completed webhook event fired when all enrichments in a batch have finished. The payload includes batchID, eventType, and a data object with enrichmentID, enrichmentCallbackURL, and message.
  • Recommendations: the reason.data field is now a typed object with changesAmount, currentJobTitle, and previousJobTitle instead of a generic map.

April 7th, 2026

  • New recommendations endpoints to fetch company and people recommendations based on an Ideal Customer Profile (ICP):

March 19th, 2026

  • The countries filter in POST /v2/companies/search now accepts world region codes (W-EMEA, W-EU, W-ME, W-AF, W-APAC, W-OC, W-AMER, W-NA, W-LATAM) in addition to ISO 3166 alpha-2 country codes.

March 12th, 2026

  • New endpoint POST /v2/people/find-by-email to search for a person given their email (reverse email enrichment). Results consume search credits.
  • Credits & Quotas article updated with the new search credits section.

October 6th, 2025

September 24th, 2025

  • Improved webhook security with signed signature header
  • Webhook documentation updated with instructions and code samples for verifying signed signatures Secure your endpoint

August 1st, 2025

July 10th, 2025

  • Credits-and-quotas and index articles updated with references to the latests endpoints.
  • Documented the max size for companies enrichment POST /v2/companies/enrich.

July 4th, 2025

June 23rd, 2025

June 17th, 2025

May 6th, 2025

  • Webhook article added here.
  • POST /v2/people/enrich now supports webhook notifications. Check the notificationOptions.webhookUrl field.

May 29th, 2025

May 21st, 2025

  • Added "savedSearch" field to POST /v1/people/search to support filter presets.
  • Refactor and stability improvements.

April 25th, 2025

April 14th, 2025

March 31st, 2025

  • Breaking changes: modified interface to /v2/people/search endpoint. Input and output payload simplified and pagination is now supported.
  • Marked /v1/people/search as deprecated.
  • Added a link to searchable values: industries, departments, and seniorities.
  • Renamed contact to person.
  • Replaced support email with api.support@surfe.com.

March 25th, 2025

  • Improved 400 response for common requests: The 400 response object has been enhanced for frequently used requests. Error messages now include detailed validation failure reasons to improve debugging and troubleshooting.
  • Move POST /v2/search/companies to POST /v2/companies/search.

March 21st, 2025

  • Added a new endpoint for Companies Search.
  • Removed beta company search /v1/organizations/search.

March 4th, 2025

  • Added organization filter includeNames to people search payload. This new attribute allows filtering by company names.

January 30th, 2025

  • Deprecated field companyID in people enrichment (single and bulk) and people search endpoint responses.
  • Added attribute organizationIDMappings to people search payload. This new attribute helps map organization domains to existing ids so that results associated with that organization will also include this id field

January 27th, 2025

  • Added field companyID in people enrichment (single and bulk) and people search endpoint responses. This is a unique identifier for the person's organization.
  • Added field confidenceScore for mobile phones in people enrichment (single and bulk) endpoint responses.
  • Added attribute peoplePerOrganization to people search payload. This new attribute helps define how many results to be returned per organization.

January 22th, 2025

  • Deprecated field clientID in people enrichment endpoints in favor of externalID
  • Deprecated request body field domains in organization's Start a bulk enrichment endpoint in favor or organizations
  • Added field externalID to organization bulk enrichment endpoints

January 20th, 2025

  • Improved the API documentation
  • Added new endpoints to support the following services:
    • Person bulk enrichment
    • People search
    • Organization bulk enrichment
    • Organization single enrichment
    • Organizations search
    • Organizations look-alikes
  • Updated Person single enrichment with new endpoint URLs and additional returned values

Previous

MCP Server

Next

Search people POST

On this page

October 2nd, 2026September 30th, 2026September 29th, 2026September 28th, 2026September 24th, 2026September 22th, 2026September 11th, 2026September 9th, 2026August 17th, 2026July 31st, 2026July 1st, 2026June 30th, 2026June 26th, 2026June 25th, 2026June 22nd, 2026June 19th, 2026June 19th, 2026June 16th, 2026June 9th, 2026June 8th, 2026June 4th, 2026May 28th, 2026May 26th, 2026May 11th, 2026May 4th, 2026April 29th, 2026April 29th, 2026April 21st, 2026April 7th, 2026March 19th, 2026March 12th, 2026October 6th, 2025September 24th, 2025August 1st, 2025July 10th, 2025July 4th, 2025June 23rd, 2025June 17th, 2025May 6th, 2025May 29th, 2025May 21st, 2025April 25th, 2025April 14th, 2025March 31st, 2025March 25th, 2025March 21st, 2025March 4th, 2025January 30th, 2025January 27th, 2025January 22th, 2025January 20th, 2025