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, location, funding, hiring and leadership changes.	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 and company signals.	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.

"I want to find companies that are hiring or have recently raised funding"
→ Use Search Companies with the hiring or funding filters.

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