1. Missing or Incorrect Authorization Header
The most common issue. Every single request to the Surfe API needs your API key included like this:
Authorization: Bearer YOUR_API_KEY
Common mistakes:
Forgetting the word
Bearerbefore the keyIncluding extra spaces or characters
Using an old or deleted API key
Not including the header at all
→ See: Find your Surfe API Key
2. Not Using the Two-Step Enrichment Flow
People and company enrichment works asynchronously — you can't get results in a single request. You must:
Start the enrichment with a POST request → receive an
enrichmentIDFetch the results with a GET request using that
enrichmentID
Trying to skip step 2 or not waiting for the enrichment to complete are the most common causes of missing data.
3. Using Invalid Filter Values
Some filters in Search People only accept pre-defined values — you can't just type any value and expect results. For example, industries, departments, seniorities and technologies all have specific accepted values.
If you use a value that isn't in the accepted list, your search may return no results or a 400 error.
Always check the accepted values first using the Get Filters endpoint before building your search.
→ See: API - Get Filters
4. Exceeding the peoplePerCompany Limit
The peoplePerCompany field only accepts values between 1 and 5. Setting it higher will cause a 400 error. If you need more results from a single company, search using a single domain and omit the peoplePerCompany parameter entirely.
→ See: API - Search People
5. Sending Too Many Requests Too Fast
The Surfe API allows up to 10 requests per second with bursts of up to 20. If you're running bulk operations and hitting 429 errors, you're sending requests too quickly.
Build a short delay between requests in your integration to stay within the limit.
→ See: API - Rate Limits
6. Not Providing Enough Data for Enrichment
The more information you provide when enriching a person, the better your find rate will be. At minimum you need a first name and last name plus one of the following:
LinkedIn URL
Company domain
Company name
Providing just a name without any company context will result in poor or no results.
7. Using an HTTP Webhook URL Instead of HTTPS
Webhook URLs must use HTTPS. If you provide an HTTP URL, Surfe will reject it. Always make sure your webhook endpoint starts with https://.
→ See: API - Webhooks
8. Exceeding the 500 Company Limit on Enrich Companies
The Enrich Companies endpoint accepts a maximum of 500 companies per request. If you need to enrich more than 500, split them into batches of 500 and send multiple requests.
→ See: API - Enrich Companies
9. Miscopying the enrichmentID
The enrichmentID returned from a start enrichment request looks similar across different requests but is unique each time. If you're getting a 404 when fetching results, double check you've copied the exact ID from the most recent start enrichment response.
10. Not Setting Up Webhooks for Large Enrichments
If you're enriching large batches of people or companies and relying on polling to check results, you're adding unnecessary load to your system and risk missing results. Webhooks are the recommended approach — they notify you automatically the moment each enrichment is complete.
→ See: API - Webhooks
Need Help?
If you're still running into issues, reach out to our support team via Intercom.