Use Case: Building a Lead List from Scratch with the Surfe API

Whether you're targeting a new market, launching a campaign, or building a pipeline from zero, the Surfe API lets you find and enrich the right people. Here's how to do it end to end.

What You'll Use

• Search People — to find professionals matching your target persona
• Enrich People — to get their verified emails and mobile numbers
• Get Filters — to make sure your search filters are valid
• Webhooks — to receive enrichment results automatically

Step 1: Define Your Target Persona

Before making any API calls, know who you're looking for. For example:

• Job title: CEO, Head of Sales, VP of Marketing
• Seniority: C-Level, Director, VP
• Industry: SaaS, Software, Internet
• Location: United Kingdom, France
• Company size: 50–500 employees

Step 2: Get Your Valid Filter Values

Some filters only accept pre-defined values. Before building your search, call the Get Filters endpoint to retrieve the accepted values for industries, departments, seniorities and more.

Endpoint: GET /v1/people/search/filters

Headers:

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Use the values returned here in your search request.

→ See: API - Get Filters

Step 3: Search for People

Use the Search People endpoint to find professionals matching your criteria.

Endpoint: POST /v2/people/search

Headers:

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body:

{
  "companies": {
    "localities": [
      {
        "countries": [
          "gb"
        ]
      }
    ],
    "employeeCount": {
      "from": 50,
      "to": 500
    },
    "industries": [
      "Software",
      "SaaS",
      "Internet"
    ]
  },
  "people": {
    "seniorities": [
      "C-Level",
      "Director"
    ],
    "jobTitles": [
      "CEO",
      "Head of Sales",
      "VP of Marketing"
    ]
  },
  "limit": 200,
  "pageToken": ""
}

The response will include a list of matching people with their name, job title, company, LinkedIn URL and more.

If there are more results available, use the nextPageToken from the response to fetch the next page.

→ See: API - Search People

Step 4: Enrich Your Results

Once you have your list of people from the search, pass them to the Enrich People endpoint to get their verified email addresses and mobile numbers.

Use externalID to map each person back to your own records.

Endpoint: POST /v2/people/enrich

Headers:

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body:

{
  "enrichmentOptions": {
    "acceptedEmailType": "professional",
    "skipMobileEnrichmentIfNoEmailFound": false
  },
  "include": {
    "email": true,
    "jobHistory": false,
    "linkedInUrl": false,
    "mobile": false
  },
  "notificationOptions": {
    "webhookUrl": "https://your-server.com/webhook"
  },
  "people": [
    {
      "firstName": "David",
      "lastName": "Chevalier",
      "companyDomain": "surfe.com",
      "linkedinUrl": "https://www.linkedin.com/in/david-maurice-chevalier",
      "externalID": "your-internal-id-123"
    }
  ]
}

You'll receive an enrichmentID in the response. Surfe will send the enriched results to your webhook URL when ready.

→ See: API - Enrich People - Understanding Surfe's Asynchronous Split Request

Step 5: Receive Your Results via Webhook

When each person's enrichment completes, Surfe sends a person.enrichment.completed event to your webhook URL with the full enriched profile including verified email, mobile number, job title, LinkedIn URL and more.

→ See: API - Webhooks

Step 6: Use Your Enriched Data

Once you have the enriched results from your webhook, your development team can use the data however works best for your workflow. For example:

• Push the data directly to your CRM using their API
• Store it in your own database using the externalID to match records back to your existing records
• Trigger automated outreach sequences by passing the data to your sales tools via their API
• Build custom workflow automation using the enriched data as a trigger for downstream processes

Things to Keep in Mind

• People search results count towards your 200 results per day quota
• People enrichment counts towards your 2,000 profiles per day quota
• Credits are only consumed when data is successfully found
• Always use externalID to keep track of which results belong to which records

→ See: API - Credits & Quotas
→ See: API - Rate limits

Need Help?

If you have any questions or need further assistance, feel free to reach out to our support team or email api.support@surfe.com.

Additional Resources

• Surfe API Documentation
• API - Search People
• API - Enrich People
• API - Get Filters
• API - Webhooks
• API - Credits & Quotas