How It Works
The Recommendations feature uses three endpoints that work together in sequence:
Create or update your ICP — define the characteristics of your target companies and people using filters like industry, location, seniority and department
Fetch recommendations — receive a list of companies and contacts that match your ICP, refreshed daily
Get your ICP filters — retrieve your saved ICP at any time to review or update it.
What is an ICP?
An ICP (Ideal Customer Profile) is a definition of the type of company and person you want to target. In Surfe's Recommendations API, your ICP is made up of two sets of filters:
Company filters:
Employee count range
Industries
Primary locations (accepts ISO 3166 alpha-2 country codes or world region codes)
Revenue range
People filters:
Countries
Departments
Job titles
Seniorities
The more filters you set, the narrower your results will be. If you receive no results, consider relaxing your ICP filters.
How Recommendations Are Refreshed
Recommendations are refreshed daily. Results are stable within a day — the same page range will always return the same companies for that day. Companies seen on a given day will not appear again on future days. Once all matching companies have been exhausted, no further results will be returned — create a new ICP with broader or different criteria to get fresh recommendations.
How Billing Works
Recommendations are charged at the end of the month based on the number of unique companies fetched. Fetching the same company multiple times — for example across multiple API calls or pages — counts as a single billable recommendation.
The Three Endpoints
Endpoint | What it does |
| Create or update your ICP |
| Fetch companies and people matching your ICP |
| Retrieve your saved ICP filters |
externalUserId
The Recommendations endpoints use externalUserId to associate an ICP with a specific user in your system. This is similar to externalID used in enrichment endpoints but specific to the Recommendations feature. If externalUserId is not provided, the ICP is associated with the authenticated user.
Need Help?
If you have any questions about the Recommendations feature, reach out to our support team via Intercom.