API - Common API Mistakes – SURFE

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 Bearer before the key
Including 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 enrichmentID
Fetch 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.

→ See: API - Enrich People - Understanding Surfe's Asynchronous Split Request

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.

→ See: API - Enrich People - Understanding Surfe's Asynchronous Split Request

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.

Additional Resources