API - Getting Started with the Surfe API

What You'll Need

• A Surfe account: Create one at Surfe.com

• An API key: Generated in your API Settings

• A tool to make API requests — like Postman or a developer to help you test.

Step 1: Get Your API Key

Log into Surfe and go to API Settings to generate your key.

A few important things to know:

• Your API key is unique to you.

• Keep it secret, anyone with your key can access your account

• If you think your key has been compromised, delete it immediately and generate a new one in API Settings

Step 2: Make Your First Request

All requests to the Surfe API need your API key in the Authorization header like this:

Authorization: Bearer YOUR_API_KEY

Here's a simple example — enriching a contact to get their email address:

curl -X POST "https://api.surfe.com/v2/people/enrich" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "include": {
      "email": true,
      "jobHistory": false,
      "linkedInUrl": false,
      "mobile": false
    },
    "notificationOptions": {
      "webhookUrl": ""
    },
    "people": [
      {
        "companyDomain": "surfe.com",
        "companyName": "Surfe",
        "externalID": "external-id",
        "firstName": "David",
        "lastName": "Chevalier",
        "linkedinUrl": "https://www.linkedin.com/in/david-maurice-chevalier"
      }
    ]
  }'

You'll receive an enrichmentID in the response. Use that to fetch your results:
​

curl -X GET "https://api.surfe.com/v2/people/enrich/YOUR_ENRICHMENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Things to Know Before You Start

Credits:
​

Surfe uses three types of credits:

• Email credits — used when enriching a contact's email address

• Mobile credits — used when enriching a contact's mobile number

• Search credits — used by the Enrich People by Email endpoint (15 credits per LinkedIn URL found)

You only spend a credit when data is successfully found. Check your balance anytime via the Get Credits endpoint or your Surfe dashboard.

Daily Quotas

Type	Daily Limit
People enrichment	2,000 profiles
People search results	200 results
Company enrichment and search	2,000
Company look-alikes	200 results

Quotas reset at midnight in your local time. Need higher limits? Contact us via intercom.

Rate Limits

Up to 10 requests per second, with bursts of up to 20. If you exceed this you'll receive a 429 Too Many Requests response — just pause and try again.

Asynchronous Enrichment

People and company enrichment works in two steps — you start the enrichment and receive an enrichmentID, then fetch the results using that ID. We recommend using Webhooks to be notified automatically when results are ready rather than polling manually.

Where to Go Next

• Find your API Key

• What is the Surfe API?

• API - Search People

• API - Enrich People

• API - Search Companies

• API - Enrich Companies

• API - Credits & Quotas

• API - Webhooks

• Full API Documentation

Need Help?

If you have any questions or need further assistance, feel free to reach out to our support team via Intercom.