Quick answers to the most common questions about how the Surfe API works, what its limits are, and what to expect in different situations.
Credits & Quotas
How many types of credits are there?
Three — email credits, mobile credits, and search credits. Email and mobile credits are used for people enrichment. Search credits are used by the Enrich People by Email endpoint, Search People, Search Companies and Enrich Companies when credit charging is enabled.
Do I get charged if no data is found?
No. Credits are only consumed when data is successfully found. If an enrichment returns a NOT_FOUND status, no credits are deducted.
How do I check my credit balance?
Use the Get Credits endpoint (GET /v1/credits) or check your Surfe dashboard. The response shows your remaining email, mobile and search credits.
→ See: API - Get Credits
What happens when I run out of credits?
You'll receive a 402 response. You can purchase additional credits at surfe.com/buy-credits.
→ See: API - Credits & Quotas
What are the daily quotas?
| Type | Free quota | With search credits |
|---|---|---|
| People enrichment | 2,000 profiles per day | - |
| People search results | 200 results per day | Up to 100,000 results per day |
| Company enrichment and search | 2,000 profiles per day | Up to 100,000 per day |
| Organization search | 200 searches per day | Up to 100,000 results per day |
When do quotas reset?
Daily at midnight in your local time.
What happens when I hit my quota?
You'll receive a 403 response. Wait until midnight for your quota to reset. If you regularly hit your quota, contact api.support@surfe.com to discuss higher limits.
What's the difference between credits and quotas?
Credits are consumed per successful data result found. Quotas are a daily limit on the number of operations regardless of whether data was found.
Do Search People and Search Companies consume credits?
When credit charging is enabled, Search People and Search Companies deduct ⌈results / 10⌉ search credits per call. Enrich Companies costs 1 search credit per successfully enriched company on paid plans — a company counts as successfully enriched when both annualRevenue and industry are present in the result. Enrich People by Email costs 10 search credits per successful match — credits are locked at request time and refunded if no match is found. A 402 response is returned when credits are insufficient. Contact the support team to request search credits.
Rate Limits
What are the rate limits?
Up to 10 requests per second, with bursts of up to 20. The rate limit resets every minute.
What happens if I exceed the rate limit?
You'll receive a 429 Too Many Requests response. Slow down your requests and try again.
Can I get higher rate limits?
Reach out to our support team or email api.support@surfe.com and we'll do our best to accommodate based on your use case and requirements.
→ See: API - Rate Limits
Enrichment Behaviour
Why does enrichment work in two steps?
Enrichment runs asynchronously — Surfe searches multiple verified sources which takes a few seconds. Rather than making you wait, Surfe returns an enrichmentID immediately and processes the enrichment in the background. You then fetch the results using that ID.
How long does enrichment take?
This depends on the size of your request and the data being processed. We recommend using webhooks to be notified automatically when your enrichment completes rather than polling manually.
How many people can I enrich in one request?
Up to 10,000 people per request.
How many companies can I enrich in one request?
Up to 500 companies per request.
What does IN_PROGRESS mean?
The enrichment is still processing. Wait a few seconds and try the GET request again, or use webhooks to be notified automatically when it completes.
What does NOT_FOUND mean?
Surfe completed the enrichment but couldn't find data for that person or company. This is expected behaviour for some records and you are not charged credits.
What is externalID and should I use it?
It's your own internal identifier that you pass in the request and Surfe returns alongside results. We recommend using it — it makes it much easier to match enriched data back to your own records without any complex lookup logic. It's not required but it will save you time.
What does skipMobileEnrichmentIfNoEmailFound do?
When set to true in the enrichmentOptions object, Surfe will skip mobile enrichment for a person if no email address is found. This helps preserve mobile credits when email enrichment is unsuccessful.
What is acceptedEmailType and when should I use it?
It's a field in the enrichmentOptions object that lets you specify which type of email to enrich. The default is "professional". Set it to "personal" to trigger the personal email cascade instead. (Personal emails cost 2 email credits per successful match. Contact api.support@surfe.com for more details).
Search Behaviour
Why is my search returning no results?
Your filters may be too specific or using invalid values. Try removing some filters and use the Get Filters endpoint to check accepted values.
→ See: API - Why Am I Getting No Data
How many results can I get per search request?
Up to 200 results per page. Use pagination with pageToken to retrieve more.
What is pageToken?
A token used to paginate through large result sets. Include the nextPageToken from one response in the next request to get the next page of results.
Can I change my filters when paginating?
No — when using a pageToken, your original filters are reused automatically. Any changes to filters in subsequent requests are ignored.
Does Surfe expand job title searches automatically? Yes — job titles provided in jobTitles are expanded automatically using acronym and semantic matching. For example searching for "CTO" will also match "Chief Technology Officer". If you need exact matching only, use the exactJobTitles filter instead.
The countries filter I was using no longer works — what do I use instead? The countries filter has been deprecated on both Search People and Search Companies as of May 4th 2026. Use the new localities filter instead — it offers more in-depth location searches including countries and world regions, specific regions within a country, specific zip codes, and free text within a company's full address.
What is organizationIDMappings and when should I use it?
It's a field in Search People that lets you map company domains to your own internal IDs. When a search result matches one of those domains, your ID is returned in the externalID field of the response — making it easy to match results back to your own records without any additional lookup.
Webhooks
Do I have to use webhooks?
No — you can poll the GET endpoint instead. But webhooks are strongly recommended for production integrations as they're more efficient and give you results instantly.
What happens if my server doesn't return 200 OK?
Surfe may retry the request. Make sure your endpoint responds with 200 OK as quickly as possible.
Does my webhook URL need to use HTTPS?
Yes — HTTP URLs are not accepted and will be rejected.
How do I verify webhook requests are from Surfe?
Use the x-surfe-signature header and your webhook shared secret to verify the HMAC signature.
→ See: API - Webhooks: Verifying Webhook Signatures
General
What format are API responses in?
All responses are JSON.
What should I do if I get a 500 error?
Wait a moment and try again. If it persists, contact our support team or email api.support@surfe.com.
Where can I find the full API documentation?
At developers.surfe.com.
Need Help?
If your question isn't answered here, reach out to our support team or email api.support@surfe.com.
Comments
0 comments
Please sign in to leave a comment.