Which API Endpoint Should I Use?

New to the Surfe API and not sure where to start? This guide breaks down every available endpoint, what it does, and when to use it — so you can find the right tool for the job quickly.

People Endpoints

Endpoint	What it does	When to use it
`POST /v2/people/search`	Search for people using filters like job title, seniority, industry, company and location	You want to find new leads matching a specific persona
`POST /v2/people/enrich`	Enrich a list of people with verified emails, mobile numbers and LinkedIn info	You have a list of contacts and want to fill in missing data
`GET /v2/people/enrich/:id`	Retrieve the results of a people enrichment job	You've started an enrichment and want to fetch the results
`POST /v2/people/find-by-email`	Look up a person's details using their email address	You have an email address and want to find out who it belongs to

Company Endpoints

Endpoint	What it does	When to use it
`POST /v2/companies/search`	Search for companies using filters like industry, revenue, employee count and location	You want to build a list of target accounts matching your ICP
`POST /v2/companies/enrich`	Enrich a list of company domains with detailed firmographic data	You have a list of company domains and want full company profiles
`GET /v2/companies/enrich/:id`	Retrieve the results of a company enrichment job	You've started a company enrichment and want to fetch the results
POST /v2/companies/signals/leadership-change	Returns the full list of leadership changes for a company	You want to see all director-level and above role changes (new hires, promotions, departures) at a specific company

Recommendations Endpoints

Endpoint	What it does	When to use it
`POST /v2/recommendations/icp`	Create or update your Ideal Customer Profile (ICP)	You want to define the characteristics of your target companies and people
`POST /v2/recommendations/fetch`	Fetch companies and people matching your ICP	You want to receive a daily-refreshed list of recommended accounts matching your ICP
`GET /v2/recommendations/icp`	Retrieve your saved ICP filters	You want to review or update your existing ICP

Utility Endpoints

Endpoint	What it does	When to use it
`GET /v1/credits`	Check your remaining email, mobile and search credit balance	Before running a large enrichment job or when you receive a 402 error
`GET /v1/people/search/filters`	Retrieve the accepted values for search filters like industries, seniorities and departments	Before building a search request to make sure your filter values are valid

Not Sure Which One to Use?

Here are some common scenarios to help you decide:

"I want to find new leads"
→ Start with Search People to find people matching your criteria, then use Enrich People to get their contact details.

"I want to enrich my existing CRM contacts"
→ Use Enrich People with your existing contact data.

"I have an email address and want to know who it belongs to"
→ Use Enrich People by Email.

"I want to build a list of target companies"
→ Use Search Companies to find matching companies, then Enrich Companies to get their full profiles.

"I'm getting a 402 error"
→ Use Get Credits to check your balance.

"My search is returning no results"
→ Use Get Filters to check you're using valid filter values.

"I want to get a daily list of recommended target accounts"

→ Use Create or Update ICP to define your ideal customer profile, then use Fetch Recommendations to receive matching companies and contacts daily.

"I want to find a personal email address for a contact"

→ Use Enrich People with acceptedEmailType: "personal" in the enrichmentOptions object.

Need Help?

If you're still not sure which endpoint is right for your use case, reach out to our support team or email api.support@surfe.com and we'll point you in the right direction.

Additional Resources

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Return to top