Whether you're enriching thousands of contacts or paginating through large search results, this guide covers everything you need to know about working with bulk data through the Surfe API efficiently and without hitting limits.
Bulk Enrichment — People
The Enrich People endpoint accepts up to 10,000 people per request. Here's how to handle large volumes effectively:
Batch your requests
Even though 10,000 is the limit per request, we recommend keeping batches to a manageable size — around 1,000 people per request. This makes it easier to handle errors, retry failed batches, and track progress.
Always use webhooks
For large enrichments, polling is impractical. Set up webhooks so your system is notified automatically as each person's enrichment completes — rather than repeatedly calling the GET endpoint.
→ See: API - Webhooks
Use externalID to track results
When sending large batches, always include an externalID for each person. This is your own internal identifier — Surfe returns it alongside the enrichment results so you can match results back to your records without complex lookup logic.
{
"firstName": "David",
"lastName": "Chevalier",
"companyDomain": "surfe.com",
"externalID": "your-crm-contact-id-123"
}Monitor your daily quota
People enrichment is limited to 2,000 profiles per day. If you're enriching large datasets, plan your batches across multiple days to stay within quota.
→ See: API - Credits & Quotas
Bulk Enrichment — Companies
The Enrich Companies endpoint accepts up to 500 companies per request.
Split large lists into batches
If you have more than 500 companies to enrich, split them into batches of 500 and send multiple requests. Use externalID on each company to track results back to your records.
Use webhooks for company enrichment too
The same logic applies as with people enrichment — webhooks are far more efficient than polling for large batches.
→ See: API - Enrich Companies
Paginating Through Large Search Results
Both Search People and Search Companies support pagination using a pageToken. Here's how it works:
Step 1 — Make your first request
Send your search request with an empty pageToken:
{
"limit": 20,
"pageToken": ""
}Limit will be consumed based on the results seen*
Step 2 — Get the nextPageToken
The response will include a nextPageToken if there are more results:
{
"people": [...],
"total": 5000,
"nextPageToken": "eyJxdWVyeUlEIjoiZWRj..."
}
Step 3 — Fetch the next page
Include the nextPageToken in your next request:
{
"limit": 200,
"pageToken": "eyJxdWVyeUlEIjoiZWRj..."
}
Step 4 — Repeat until done
Keep repeating until the response no longer includes a nextPageToken — that means you've reached the last page.
Important: When using a pageToken, your original filters are reused automatically. Any changes to filters in subsequent requests are ignored.
Watch your daily quota
People search results count towards your 200 results per day quota. If you're paginating through large result sets, be mindful of how quickly you'll hit that limit.
→ See: API - Credits & Quotas
Rate Limits During Bulk Operations
When running bulk operations, it's easy to hit the rate limit of 10 requests per second. Build a short delay between requests to stay within the limit and handle 429 responses gracefully with a retry strategy.
→ See: API - Rate Limits
Summary
Operation | Limit per request | Daily quota |
Enrich People | 10,000 people | 2,000 profiles |
Enrich Companies | 500 companies | 2,000 companies |
Search People | 200 results per page | 200 results |
Search Companies | 200 results per page | 2,000 companies |
Need Help?
If you're planning a large enrichment job and want to discuss your options, reach out to our support team via Intercom.
Additional Resources