API - Handling Bulk Requests and Large Result Sets

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

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

• Surfe API Documentation

• Webhooks

• Find your API key

• Setting up the API

• Terms & Conditions of using our API