Bulk Enrich Contact Data from CSV with Surfe API: Python Code Tutorial

by Georgia James May 21, 2025

2 Min. Read

Your outreach is only as effective as the data you’re working with. And let’s be honest — most contact lists are full of holes. No verified email addresses. No phone number. Just a name and a company, if you’re lucky. That’s not just incomplete — it’s costing you opportunities.

This tutorial shows you how to fix that with a simple Python script. Using Surfe’s Contact Enrichment API, you’ll take a CSV file of partially complete contacts, enrich them in bulk with verified data, and generate a clean, updated list you can use right away.

Upload the file, run the script, and let Surfe do the heavy lifting — so your team can focus on selling, not searching.

By the end of this tutorial, you’ll have a fully functioning Python script that:

Reads a CSV file of contacts
Extracts key information
Sends bulk enrichment requests to Surfe’s API
Retrieves enriched detailed contact data
Compares old vs new information, updates any outdated information, and fills any missing information
Outputs a new, enriched CSV ready to use in your sales process

Want the full script? Jump to the bottom or view it on GitHub!

Prerequisites

Python 3.x installed

Most modern operating systems come with Python 3 pre-installed. To check if Python is installed on your system:

Windows: Open Command Prompt (Win + R, type cmd, press Enter) and run:

py --version

macOS/Linux: Open Terminal and run:’

python3 --version

If Python is not installed, download it from the official Python website (or beginner guide to downloads) and follow the installation instructions for your OS.

Basic Python knowledge
Surfe account and API key

To use Surfe’s API, you’ll need to create an account and obtain an API key. You can find the API documentation and instructions for generating your API key here: Surfe Developer Docs.

Step 1: Setting Up Your Environment

1.1 Creating a Virtual Environment (Optional but Recommended)

To keep your dependencies organized, you can create a virtual environment:

# macOS/Linux

python3 -m venv env

source env/bin/activate 

# Windows

py -m venv env

env\Scripts\activate

1.2 Installing Required Packages

Ensure you have the following packages installed:

requests (for API calls)
python-dotenv (for storing API keys securely)

# macOS/Linux

python3 -m pip install requests python-dotenv

# Windows

py -m pip install requests python-dotenv

1.3 Setting Up Your API Key Securely

It’s best to avoid hardcoding API keys in your script. Instead, store them in environment variables:

Create a .env file in your project root:

SURFE_API_KEY=YOUR_API_KEY

Create your python script file contact_enrichment.py, add all package imports, and load the key in your Python script:

import csv

import requests

import time

import os

from typing import Dict, List, Any

from dotenv import load_dotenv

# Load environment variables from .env file

load_dotenv()

api_key = os.getenv('SURFE_API_KEY')

Step 2: Preparing Your Contact Data

For this example, we’ll use a CSV file with partial contact information. In production, you would typically use either a CSV uploader, fetch directly from a cloud storage bucket, connect directly to your CRM, or pull data from other third-party APIs.

2.1 CSV File Format Requirements

Your CSV file should contain some or all of the following columns:

First Name
Last Name
Company Name
Company Domain
Email Address
Mobile Phone Number
Job Title
LinkedIn Profile URL

The enrichment process requires at least one of the following:

A LinkedIn URL
A combination of “First Name + Last Name + Company Name”
A combination of “First Name + Last Name + Company Domain”

But otherwise, Not all fields need to be populated – the enrichment process will attempt to fill in missing information and verify existing data as long as you provide the required minimum identifiers

2.2 Sample Input Data

Create a sample sample_input.csv file with some incomplete contact information:

Step 3: Building the Enrichment Script

Now we’ll build our enrichment script by breaking down each component function:

Step 3.1: Setting Up Constants and Creating a Parser for Input Data

First, let’s define our API endpoints. These are the URLs we’ll use to interact with Surfe’s API. They point to:

Enrich People (start): Starts bulk enriching the provided list of people and returns an enrichment ID
Enrich People (get): returns the corresponding enrichment’s progress. Once it is completed, the response will also include the enrichment results.

BULK_ENRICHMENT_ENDPOINT = "https://api.surfe.com/v1/people/enrichments/bulk"

GET_BULK_ENRICHMENT_ENDPOINT = "https://api.surfe.com/v1/people/enrichments/bulk/"

Next, we need to create a function that reads our CSV file and transforms it into the format expected by Surfe’s API. This function will:

Open and read the CSV file
Extract the relevant fields for each contact
Create a unique identifier for each contact
Format the data according to the API requirements

def create_enrichment_payload(input_file: str) -> List[Dict[str, str]]:

       people = []

       with open(input_file, 'r', encoding='utf-8') as csvfile:

        reader = csv.DictReader(csvfile)

        for row in reader:

            person = {

                "firstName": row["First Name"],

                "lastName": row["Last Name"],

                "companyName": row["Company Name"],

                "companyWebsite": row["Company Domain"],

                "externalID": f"{row['First Name']}_{row['Last Name']}".lower().replace(" ", "_"),

                "linkedinUrl": row["LinkedIn Profile URL"]

            }

            # Remove empty fields

            person = {k: v for k, v in person.items() if v}

            people.append(person)

       return people

Step 3.2: Implementing the API Request Functions

To securely communicate with Surfe’s API, we need to properly authenticate our requests. The first part of this function sets up the necessary authentication headers using the API key:

def start_bulk_enrichment(api_key: str, people: List[Dict[str, str]]) -> str:

    headers = {

        'Authorization': f'Bearer {api_key}',

        'Content-Type': 'application/json'

    }

Step 3.3: Creating the Request Payload

Now, we need to create the payload that contains all the information Surfe needs to enrich our contacts. This includes the type of enrichment we want (email, or both email and phone) and a name for our list:

    payload = {

        "enrichmentType": "emailAndMobile",  

        "listName": f"Contact Enrichment {time.strftime('%Y-%m-%d %H:%M:%S')}",

        "people": people

    }

Step 3.4: Sending the API Request

Once our payload is ready, we send it to Surfe’s API endpoint. This is a POST request that initiates the enrichment process:

   response = requests.post(

        BULK_ENRICHMENT_ENDPOINT,

        headers=headers,

        json=payload

    )

Step 3.5: Handling API Errors

We need to check if our request was successful and handle any errors. A successful request should return a 202 status code. If we get any other status code, we raise an exception with the error message:

     if response.status_code != 202:

        raise Exception(f"API request failed with status code {response.status_code}: {response.text}")

        response_data = response.json()

    return response_data["id"

]

Here’s the complete start_bulk_enrichment function:

def start_bulk_enrichment(api_key: str, people: List[Dict[str, str]]) -> str:

    headers = {

        'Authorization': f'Bearer {api_key}',

        'Content-Type': 'application/json'

    }

       payload = {

        "enrichmentType": "emailAndMobile",  # Request both email and mobile enrichment

        "listName": f"Contact Enrichment {time.strftime('%Y-%m-%d %H:%M:%S')}",

        "people": people

    }

       response = requests.post(

        BULK_ENRICHMENT_ENDPOINT,

        headers=headers,

        json=payload

    )

       if response.status_code != 202:

        raise Exception(f"API request failed with status code {response.status_code}: {response.text}")

       response_data = response.json()

    return response_data["id"]

Step 3.6: Polling for Results

The Enrichment API works in two steps: first, you submit an enrichment request, and Surfe returns a unique request ID. Then, using this request ID, you wait for Surfe to gather the contact details and retrieve the results once they are ready.

The time taken to complete enrichment requests can vary dependant on the size of request, typically requests are completed within a few seconds. In our example to keep the logic fairly simple, we will be checking if the request is completed every 0.5 seconds in a loop. We know the enrichment request is finished when status = completed.

Let’s create a function to check the status of our enrichment job and retrieve the results when they’re ready:

def check_enrichment_status(api_key: str, job_id: str) -> Dict[str, Any]:

    headers = {

        'Authorization': f'Bearer {api_key}'

    }

      response = requests.get(

        f"{GET_BULK_ENRICHMENT_ENDPOINT}{job_id}",

        headers=headers

    )

       if response.status_code != 200:

        raise Exception(f"API request failed with status code {response.status_code}: {response.text}")

       return response.json()

Step 3.7: Processing the Enriched Data – Contact Mapping

Now that we have our enriched data, we need to match it with our original contacts and update them. First, let’s create a function to map our original contacts and process the enriched contacts:

def compare_and_update_data(original_data: List[Dict[str, str]], enriched_people: List[Dict[str, Any]]) -> List[Dict[str, Any]]:

    updated_data = []

       # Create a mapping of original data by external ID

    original_map = {}

    for person in original_data:

        key = person.get("externalID", "").lower()

        if not key and "firstName" in person and "lastName" in person:

            key = f"{person['firstName']}_{person['lastName']}".lower().replace(" ", "_")

        original_map[key] = person

      # Process each enriched contact

    for enriched in enriched_people:

        # Find the corresponding original contact

        external_id = enriched.get("externalID", "").lower()

        original = original_map.get(external_id, {})

Step 3.8: Processing the Enriched Data – Extract Email Information

The enriched data from Surfe includes email addresses in an array format, potentially with validation status. We need to extract the best email:

      email = ""

        if "emails" in enriched and enriched["emails"]:

            # First try to find a validated email

            for email_obj in enriched["emails"]:

                if email_obj.get("validationStatus") == "VALID":

                    email = email_obj.get("email", "")

                    break

            # If no validated email was found, use the first one

            if not email and enriched["emails"]:

                email = enriched["emails"][0].get("email", "")

Step 3.9: Processing the Enriched Data – Extract Mobile Phone Information

Similarly, we need to extract mobile phone numbers, which come with confidence scores:

# Extract mobile phone from the mobilePhones array

        mobile_phone = ""

        if "mobilePhones" in enriched and enriched["mobilePhones"]:

            # Sort by confidence score if available (highest first)

            sorted_phones = sorted(

                enriched["mobilePhones"], 

                key=lambda x: x.get("confidenceScore", 0), 

                reverse=True

            )

            mobile_phone = sorted_phones[0].get("mobilePhone", "")

Step 3.10: Processing the Enriched Data – Create Updated Records

Now we create updated records that combine the original and enriched data:

        # Create updated record with comparison information

        updated = {

            "First Name": enriched.get("firstName", original.get("firstName", "")),

            "Last Name": enriched.get("lastName", original.get("lastName", "")),

            "Company Name": enriched.get("companyName", original.get("companyName", "")),

            "Company Domain": enriched.get("companyWebsite", original.get("companyWebsite", "")),

            "Email Address": email,

            "Mobile Phone Number": mobile_phone,

            "Job Title": enriched.get("jobTitle", original.get("jobTitle", "")),

            "LinkedIn Profile URL": enriched.get("linkedinUrl", original.get("linkedinUrl", "")),

            "Update Status": determine_update_status(original, enriched, email, mobile_phone)

        }

               updated_data.append(updated)

      return updated_data

Step 3.11: Determining Update Status

To help understand what data was updated or filled in, we’ll create a function that checks what changed between the original and enriched data:

Here’s the complete `compare_and_update_data` function:

def compare_and_update_data(original_data: List[Dict[str, str]], enriched_people: List[Dict[str, Any]]) -> List[Dict[str, Any]]:

    updated_data = []

        # Create a mapping of original data by external ID

    original_map = {}

    for person in original_data:

        key = person.get("externalID", "").lower()

        if not key and "firstName" in person and "lastName" in person:

            key = f"{person['firstName']}_{person['lastName']}".lower().replace(" ", "_")

        original_map[key] = person

       # Process each enriched contact

    for enriched in enriched_people:

        # Find the corresponding original contact

        external_id = enriched.get("externalID", "").lower()

        original = original_map.get(external_id, {})

        # Extract email from the emails array

        email = ""

        if "emails" in enriched and enriched["emails"]:

            # First try to find a validated email

            for email_obj in enriched["emails"]:

                if email_obj.get("validationStatus") == "VALID":

                    email = email_obj.get("email", "")

                    break

            # If no validated email was found, use the first one

            if not email and enriched["emails"]:

                email = enriched["emails"][0].get("email", "")

                # Extract mobile phone from the mobilePhones array

        mobile_phone = ""

        if "mobilePhones" in enriched and enriched["mobilePhones"]:

            # Sort by confidence score if available (highest first)

            sorted_phones = sorted(

                enriched["mobilePhones"], 

                key=lambda x: x.get("confidenceScore", 0), 

                reverse=True

            )

            mobile_phone = sorted_phones[0].get("mobilePhone", "")

        # Create updated record with comparison information

        updated = {

            "First Name": enriched.get("firstName", original.get("firstName", "")),

            "Last Name": enriched.get("lastName", original.get("lastName", "")),

            "Company Name": enriched.get("companyName", original.get("companyName", "")),

            "Company Domain": enriched.get("companyWebsite", original.get("companyWebsite", "")),

            "Email Address": email,

            "Mobile Phone Number": mobile_phone,

            "Job Title": enriched.get("jobTitle", original.get("jobTitle", "")),

            "LinkedIn Profile URL": enriched.get("linkedinUrl", original.get("linkedinUrl", "")),

            "Update Status": determine_update_status(original, enriched, email, mobile_phone)

        }

               updated_data.append(updated)

      return updated_data

Step 3.12: Saving the Results to CSV

Finally, we need a function to save our enriched data to a CSV file:

def save_output_csv(output_file: str, data: List[Dict[str, Any]]):

    if not data:

        return

        # Get the column names from the first record

    fieldnames = list(data[0].keys())

        # Write the data to a CSV file

    with open(output_file, 'w', newline='', encoding='utf-8') as csvfile:

        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

        writer.writeheader()

        writer.writerows(data)

Step 3.13: Main Function – Putting It All Together

Now let’s create the main function that ties everything together, The following flow explains how all the pieces gets tied together

def main():

    import argparse

       # Parse command line arguments

    parser = argparse.ArgumentParser(description="Enrich contact information using Surfe API")

    parser.add_argument("--input", required=True, help="Input CSV file path")

    parser.add_argument("--output", required=True, help="Output CSV file path")

    parser.add_argument("--poll-interval", type=int, default=5, help="Polling interval in seconds")

    args = parser.parse_args()

       # Get the API key from environment variables

    api_key = os.getenv('SURFE_API_KEY')

    if not api_key:

        print("Error: SURFE_API_KEY environment variable not set. Please set it or create a .env file.")

        return 1

    try:

        # Step 1: Parse input file and create payload

        print(f"Parsing input file: {args.input}")

        people = create_enrichment_payload(args.input)

        print(f"Found {len(people)} contacts to enrich")

                # Step 2: Start bulk enrichment

        print("Starting bulk enrichment job...")

        job_id = start_bulk_enrichment(api_key, people)

        print(f"Enrichment job started with ID: {job_id}")

                # Step 3: Poll for results

        print("Waiting for enrichment job to complete...")

        while True:

            status_data = check_enrichment_status(api_key, job_id)

                        if status_data["status"] == "COMPLETED":

                print("Enrichment job completed successfully")

                enriched_people = status_data["people"]

                break

            elif status_data["status"] == "FAILED":

                raise Exception(f"Enrichment job failed: {status_data.get('error', 'Unknown error')}")

                        print(f"Job status: {status_data['status']}. Waiting {args.poll_interval} seconds...")

            time.sleep(args.poll_interval)

                # Step 4: Compare and update data

        print("Comparing original data with enriched data...")

        updated_data = compare_and_update_data(people, enriched_people)

               # Step 5: Save output to CSV

        print(f"Saving updated data to: {args.output}")

        save_output_csv(args.output, updated_data)

                print("Contact enrichment completed successfully")

            except Exception as e:

        print(f"Error: {str(e)}")

        return 1

        return 0

if __name__ == "__main__":

    exit(main())

Step 4: Running the Script

Now that we’ve built our script, let’s run it to enrich our contacts.

Ensure your .env file contains your API key:

SURFE_API_KEY=your_api_key_here

3. Open your terminal or command prompt, navigate to the directory containing your script, and run:

python contact_enrichment.py --input sample_input.csv --output enriched_contacts.csv

The script will:

Parse the input CSV
Start the enrichment job
Poll for results until completion
Create an enriched output CSV

Check the enriched_contacts.csv file, which should contain:

All original fields
Updated information from the enrichment
A new “Update Status” column showing what changed

What to expect

Complete Code for Easy Integration

#!/usr/bin/env python3
import argparse
import csv
import json
import os
import requests
import time
from typing import Dict, List, Optional, Any
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# API endpoints
BULK_ENRICHMENT_ENDPOINT = "https://api.surfe.com/v1/people/enrichments/bulk"
GET_BULK_ENRICHMENT_ENDPOINT = "https://api.surfe.com/v1/people/enrichments/bulk/"

def create_enrichment_payload(input_file: str) -> List[Dict[str, str]]:
"""
Parse the input CSV file and create the payload for the bulk enrichment API.
"""
people = []

with open(input_file, 'r', encoding='utf-8') as csvfile:
reader = csv.DictReader(csvfile)
for row in reader:
person = {
"firstName": row["First Name"],
"lastName": row["Last Name"],
"companyName": row["Company Name"],
"companyWebsite": row["Company Domain"],
"externalID": f"{row['First Name']}_{row['Last Name']}".lower().replace(" ", "_"),
"linkedinUrl": row["LinkedIn Profile URL"]
}
# Remove empty fields
person = {k: v for k, v in person.items() if v}
people.append(person)

return people

def start_bulk_enrichment(api_key: str, people: List[Dict[str, str]]) -> str:
"""
Start a bulk enrichment job and return the job ID.
"""
headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}

payload = {
"enrichmentType": "emailAndMobile",
"listName": f"Contact Enrichment {time.strftime('%Y-%m-%d %H:%M:%S')}",
"people": people
}

response = requests.post(
BULK_ENRICHMENT_ENDPOINT,
headers=headers,
json=payload
)

if response.status_code != 202:
raise Exception(f"API request failed with status code {response.status_code}: {response.text}")

response_data = response.json()
return response_data["id"]

def check_enrichment_status(api_key: str, job_id: str) -> Dict[str, Any]:
"""
Check the status of a bulk enrichment job.
"""
headers = {
'Authorization': f'Bearer {api_key}'
}

response = requests.get(
f"{GET_BULK_ENRICHMENT_ENDPOINT}{job_id}",
headers=headers
)

if response.status_code != 200:
raise Exception(f"API request failed with status code {response.status_code}: {response.text}")

return response.json()

def compare_and_update_data(original_data: List[Dict[str, str]], enriched_people: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""
Compare original data with enriched data to fill gaps and update incorrect information.
"""
updated_data = []

# Create a mapping of original data by external ID
original_map = {}
for person in original_data:
key = person.get("externalID", "").lower()
if not key and "firstName" in person and "lastName" in person:
key = f"{person['firstName']}_{person['lastName']}".lower().replace(" ", "_")
original_map[key] = person

for enriched in enriched_people:
# Find the corresponding original contact
external_id = enriched.get("externalID", "").lower()
original = original_map.get(external_id, {})

# Extract email from the emails array
email = ""
if "emails" in enriched and enriched["emails"]:
for email_obj in enriched["emails"]:
if email_obj.get("validationStatus") == "VALID":
email = email_obj.get("email", "")
break
if not email and enriched["emails"]:
email = enriched["emails"][0].get("email", "")

# Extract mobile phone from the mobilePhones array
mobile_phone = ""
if "mobilePhones" in enriched and enriched["mobilePhones"]:
# Sort by confidence score if available
sorted_phones = sorted(
enriched["mobilePhones"],
key=lambda x: x.get("confidenceScore", 0),
reverse=True
)
mobile_phone = sorted_phones[0].get("mobilePhone", "")

# Create updated record with comparison information
updated = {
"First Name": enriched.get("firstName", original.get("firstName", "")),
"Last Name": enriched.get("lastName", original.get("lastName", "")),
"Company Name": enriched.get("companyName", original.get("companyName", "")),
"Company Domain": enriched.get("companyWebsite", original.get("companyWebsite", "")),
"Email Address": email,
"Mobile Phone Number": mobile_phone,
"Job Title": enriched.get("jobTitle", original.get("jobTitle", "")),
"LinkedIn Profile URL": enriched.get("linkedinUrl", original.get("linkedinUrl", "")),
"Update Status": determine_update_status(original, enriched, email, mobile_phone)
}

updated_data.append(updated)

return updated_data

def determine_update_status(original: Dict[str, str], enriched: Dict[str, Any], email: str, mobile_phone: str) -> str:
"""
Determine the update status for a contact by comparing original and enriched data.
"""
field_mapping = {
"firstName": "First Name",
"lastName": "Last Name",
"companyName": "Company Name",
"companyWebsite": "Company Domain",
"jobTitle": "Job Title",
"linkedinUrl": "LinkedIn Profile URL"
}

# Special handling for email and phone which are in arrays in the API response
special_fields = {
"email": "Email Address",
"mobilePhone": "Mobile Phone Number"
}

updates = []
filled_gaps = []

# Check regular fields
for api_field, csv_field in field_mapping.items():
orig_value = original.get(api_field, "")
new_value = enriched.get(api_field, "")

# Skip if both are empty or there's no change
if (not orig_value and not new_value) or orig_value == new_value:
continue

# Check if we filled a gap
if not orig_value and new_value:
filled_gaps.append(csv_field)
# Check if information was updated
elif orig_value and new_value and orig_value != new_value:
updates.append(csv_field)

# Check email
orig_email = original.get("email", "")
if orig_email != email:
if not orig_email and email:
filled_gaps.append("Email Address")
elif orig_email and email and orig_email != email:
updates.append("Email Address")

# Check mobile phone
orig_phone = original.get("phone", "")
if orig_phone != mobile_phone:
if not orig_phone and mobile_phone:
filled_gaps.append("Mobile Phone Number")
elif orig_phone and mobile_phone and orig_phone != mobile_phone:
updates.append("Mobile Phone Number")

if updates and filled_gaps:
return f"Updated: {', '.join(updates)}; Filled: {', '.join(filled_gaps)}"
elif updates:
return f"Updated: {', '.join(updates)}"
elif filled_gaps:
return f"Filled: {', '.join(filled_gaps)}"
else:
return "No changes"

def save_output_csv(output_file: str, data: List[Dict[str, Any]]):
"""
Save the updated data to a CSV file.
"""
if not data:
return

fieldnames = list(data[0].keys())

with open(output_file, 'w', newline='', encoding='utf-8') as csvfile:
writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
writer.writeheader()
writer.writerows(data)

def main():
parser = argparse.ArgumentParser(description="Enrich contact information using Surfe API")
parser.add_argument("--input", required=True, help="Input CSV file path")
parser.add_argument("--output", required=True, help="Output CSV file path")
parser.add_argument("--poll-interval", type=int, default=5, help="Polling interval in seconds")
args = parser.parse_args()

api_key = os.getenv('SURFE_API_KEY')
if not api_key:
print("Error: SURFE_API_KEY environment variable not set. Please set it or create a .env file.")
return 1

try:
# Parse input file and create payload
print(f"Parsing input file: {args.input}")
people = create_enrichment_payload(args.input)
print(f"Found {len(people)} contacts to enrich")

# Start bulk enrichment
print("Starting bulk enrichment job...")
job_id = start_bulk_enrichment(api_key, people)
print(f"Enrichment job started with ID: {job_id}")

# Poll for results
print("Waiting for enrichment job to complete...")
while True:
status_data = check_enrichment_status(api_key, job_id)

if status_data["status"] == "COMPLETED":
print("Enrichment job completed successfully")
enriched_people = status_data["people"]
break
elif status_data["status"] == "FAILED":
raise Exception(f"Enrichment job failed: {status_data.get('error', 'Unknown error')}")

print(f"Job status: {status_data['status']}. Waiting {args.poll_interval} seconds...")
time.sleep(args.poll_interval)

# Compare and update data
print("Comparing original data with enriched data...")
updated_data = compare_and_update_data(people, enriched_people)

# Save output to CSV
print(f"Saving updated data to: {args.output}")
save_output_csv(args.output, updated_data)

print("Contact enrichment completed successfully")

except Exception as e:
print(f"Error: {str(e)}")
return 1

return 0

if __name__ == "__main__":
exit(main())

Final Notes: Credits, Quotas, and Rate Limiting

Credits & Quotas

Surfe’s API uses a credit system for people enrichment. Retrieving email, landline, and job details consumes email credits, while retrieving mobile phone numbers consumes mobile credits. There are also daily quotas, such as 2,000 people enrichments per day and 200 organization look-alike searches per day. For more information on credits and quotas, please speak to a Surfe representative to discuss a tailored plan that works for you and your business needs. Quotas reset at midnight (local time), and additional credits can be purchased if needed. For full details, refer to the Credits & Quotas documentation.

Rate Limiting

Surfe enforces rate limits to ensure fair API usage. Users can make up to 10 requests per second, with short bursts of up to 20 requests allowed. The limit resets every minute. Exceeding this results in a 429 Too Many Requests error, so it’s recommended to implement retries in case of rate limit issues. Learn more in the Rate Limits documentation.

Contact Enrichment API FAQs

What Is a Contact Enrichment API?

A contact enrichment API is a tool that fills in the gaps in your CRM data by adding missing contact details — like job title, seniority, company website, email address, and phone number. For sales teams, this means no more guessing who to reach out to or wasting time manually researching leads. Instead, you get complete, up-to-date contact profiles delivered straight into your CRM.

Why Do Sales Teams Need a Contact Enrichment API?

Sales teams move fast — but incomplete data slows everything down. A contact enrichment API helps you quickly identify high-value leads, prioritize outreach, and personalize your messaging. Instead of cold emails to “info@” addresses, you get verified contact info that helps you land in the right inbox, every time.

What’s the Difference Between a Contact Enrichment API and Other Data Tools?

Most traditional data tools require manual CSV uploads, long setup times, or separate platforms to search for leads. A contact enrichment API plugs directly into your workflow. It works with your CRM and enriches contact data programmatically — so you don’t need to copy, paste, or switch tabs to get the info you need.

What Data Can I Enrich with Surfe’s API?

Surfe’s API can return:

Verified email addresses (work and personal)
Mobile and landline numbers
Job titles and seniority
Company name and website
Location and department
Social profiles (LinkedIn, Meta, X, etc.)

The more input data you provide (like full name + company), the better the results.

Do I Need a Developer to Use the API?

Not necessarily. If you’re comfortable running basic Python scripts, you can follow this guide and set it up yourself — no full dev team required. And if you get stuck, tools like ChatGPT can help generate or fix the code.

How Often Can I Run the Enrichment Script?

You can run it as often as your workflow requires — once a day, once a week, or whenever new contacts are added to Pipedrive. Just be mindful of your API usage and credit limits depending on your Surfe plan.

Can I Combine Surfe’s API with Other Tools?

Yes! Once you’ve enriched your contacts, you can push that data into your email platform, sales engagement tool, or even trigger workflows using tools like Zapier. It’s flexible, scalable, and works with whatever your stack looks like.