Use Case: Building a Target Account List with Company Search

You know the type of company you want to target — the industry, the size, the location — but you don't have a list yet. The Surfe API lets you build a targeted account list from scratch using the Company Search endpoint, then enrich those companies with detailed profile data. Here's how.

What You'll Use

• Search Companies — to find companies matching your ideal customer profile
• Enrich Companies — to get detailed company data for your target accounts
• Webhooks — to receive enrichment results automatically

When to Use This

This workflow is ideal when you want to:

• Build a list of target accounts matching your ICP
• Find companies in a specific industry, region or revenue range
• Enrich a list of company domains with firmographic data
• Identify new markets or segments to target

Step 1: Search for Target Companies

Use the Search Companies endpoint to find companies matching your criteria.

Endpoint: POST /v2/companies/search

Headers:

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

Request Body:

{
  "filters": {
    "localities": [
      {
        "countries": [
          "gb"
        ]
      }
    ],
    "employeeCount": {
      "from": 50,
      "to": 500
    },
    "industries": [
      "Software",
      "SaaS",
      "Internet"
    ],
    "revenue": {
      "from": 1000000,
      "to": 50000000
    }
  },
  "limit": 200,
  "pageToken": ""
}

Adjust the filter values to match your target criteria. Use the Get Filters endpoint to see accepted values for industries and other filters.

The response will include a list of matching companies with their name, domain, industry, employee count and revenue range.

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

→ See: API - Search Companies

Step 2: Enrich Your Target Companies

Once you have your list of company domains from the search results, pass them to the Enrich Companies endpoint to get detailed firmographic data.

You can include up to 500 companies per request. If your list is larger, split it into batches.

Endpoint: POST /v2/companies/enrich

Headers:

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

Request Body:

{
  "companies": [
    {
      "domain": "surfe.com",
      "externalID": "account-id-001"
    },
    {
      "domain": "example.com",
      "externalID": "account-id-002"
    }
  ],
  "notificationOptions": {
    "webhookUrl": "https://your-server.com/webhook"
  }
}

You'll receive an enrichmentID in the response confirming the enrichment has started.

→ See: API - Enrich Companies

Step 3: Receive Results via Webhook

When each company enrichment completes, Surfe sends a company.enrichment.completed event to your webhook URL with the full company profile.

Example webhook payload:

{
  "eventType": "company.enrichment.completed",
  "data": {
    "enrichmentID": "01973b15-68d2-7937-b87c-78dd0069b2db",
    "company": {
      "externalID": "account-id-001",
      "name": "Surfe",
      "websites": [
        "surfe.com"
      ],
      "description": "Sales teams waste too much time on repetitive admin tasks.",
      "employeeCount": 65,
      "founded": "2020",
      "hqCountry": "FR",
      "hqAddress": "52 Rue Chaussée D'antin Paris FR 75009",
      "industry": "IT Services",
      "subIndustry": "Internet Services & Infrastructure",
      "revenue": "10-50M",
      "linkedInURL": "https://linkedin.com/company/surfe",
      "isPublic": false,
      "followersCountLinkedin": 8896,
      "status": "COMPLETED"
    }
  }
}

Use the externalID in the payload to match the enriched data back to the correct account in your system.

→ See: API - Webhooks

Step 4: Find People at Your Target Accounts

Once you have your enriched company list, use the Search People endpoint to find the right contacts at each company. Pass the company domains from your enriched list as filters.

Endpoint: POST /v2/people/search

Headers:

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

Request Body:

{
  "companies": {
    "domains": [
      "surfe.com",
      "example.com"
    ]
  },
  "people": {
    "seniorities": [
      "C-Level",
      "Director"
    ],
    "jobTitles": [
      "CEO",
      "Head of Sales"
    ]
  },
  "limit": 200,
  "pageToken": ""
}

Adjust the filter values to match your target persona. Use the Get Filters endpoint to see accepted values for seniorities and job titles.

→ See: API - Search People

Step 5: Use Your Target Account List

Once your development team has the enriched company and people data, they can use it to:

• Load target accounts and contacts into your CRM via their API
• Build account-based outreach sequences using the verified contact details
• Store enriched profiles in your own database using externalID to match records
• Build dashboards or reports from the firmographic data

Things to Keep in Mind

• Company search results count towards your 200 look-alikes per day quota
• Company enrichment counts towards your 2,000 companies per day quota
• People search results count towards your 200 results per day quota
• Always use externalID to match results back to your own records
• For company lists larger than 500, split into batches of 500
• On paid plans, each successfully enriched company costs 1 search credit — only charged when both annualRevenue and industry are present in the result. The first 2,000 enrichments per day are covered by your free quota

→ See: API - Credits & Quotas

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 Companies
• API - Enrich Companies
• API - Search People
• API - Webhooks
• API - Credits & Quotas