API - Checklist Before Going Live

Your API key is stored securely and not hardcoded into your codebase

Your API key is not exposed publicly in client-side code or public repositories

You have a plan for rotating your API key if it's ever compromised

Every request includes the correct Authorization: Bearer YOUR_API_KEY header

You're using the two-step async flow correctly — POST to start, GET to retrieve results

You're handling IN_PROGRESS status correctly and not treating it as an error

You're using webhooks rather than polling for production enrichments

Your webhook URL is publicly accessible and uses HTTPS

Your webhook endpoint responds with 200 OK immediately on receipt

You're using externalID to map enrichment results back to your own records

Your webhook endpoint is live and publicly accessible

You've tested your endpoint using a real enrichment request

You've implemented signature verification to confirm requests are from Surfe

You've implemented replay attack protection by checking the timestamp

You're using the enrichmentID to deduplicate any retried notifications

You're sending no more than 10 requests per second

You've built retry logic with a short delay for 429 responses

You understand your daily quotas and have planned your usage accordingly

You've checked your credit balance and have enough for your planned usage

You know what happens when credits or quotas run out and have handled those error codes

Your integration handles all response codes gracefully — 400, 401, 402, 403, 404, 429, 500, 503

You're logging errors with enough detail to debug issues in production

You have a process for alerting your team when something goes wrong

You're not silently swallowing errors

You're providing as much information as possible when enriching people (LinkedIn URL, company domain, full name)

You've tested enrichment with a sample of your real data before going live

You have a plan for handling NOT_FOUND results

You understand that credits are only consumed when data is successfully found

If enriching companies, you're sending no more than 500 per request

If enriching people, you're aware the limit is 10,000 per request

You've split large datasets into manageable batches

You've tested with a small batch before running a large enrichment job

Surfe API Documentation

Webhooks

Find your API key

Setting up the API

Terms & Conditions of using our API