Surfe

Surfe People API

Search and enrich individual contacts.

GitHub OpenAPI
Business capability
Company & Contact Data AE-230.30

Operations 4

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /people/search Search people by persona and company filters · Search people #
Ask an LLM
“How do I find prospects by job title and seniority at companies in a certain industry?”
“Can I limit how many people come back per company in a people search?”
Tell an agent
Find up to {limit} people with persona filters {people} at companies matching {companies}.
Search for {limit} prospects matching {people}, at most {peoplePerCompany} per company.
POST /people/enrich Start a bulk people enrichment job · Enrich people (start) #
Ask an LLM
“How do I get verified emails and mobile numbers for a list of LinkedIn profiles?”
“Can I enrich contacts using just first name, last name and company domain?”
Tell an agent
Start enriching {people} to retrieve {include}.
Kick off a people enrichment for {people} returning {include}, and notify me via {notificationOptions}.
GET /people/enrich/{id} Get a people enrichment job's results · Enrich people (get) #
Ask an LLM
“Is my contact enrichment job completed yet?”
“Where can I pick up the emails and phone numbers from a people enrichment I already started?”
Tell an agent
Check the status of people enrichment job {id}.
Get the enriched contact details from people enrichment job {id}.
POST /people/find-by-email Look up people from email addresses · Find people by email #
Ask an LLM
“Can I look up who owns an email address and what company they work for?”
“What profile and firmographic data comes back when I enrich from a list of emails?”
Tell an agent
Find the person profiles behind these email addresses: {emails}.
Look up {emails} and tell me each person's company.

Documentation

📖
Documentation
https://developers.surfe.com/public-009-search-people-v2
📖
APIReference
https://developers.surfe.com/

Specifications

⚙
OpenAPI
https://artifacts.apis.io/surfe/openapi/surfe-people-api-openapi.yml

Other Resources

🔗
Overlay
https://artifacts.apis.io/surfe/overlays/surfe-people-overlay.yaml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/surfe:surfe-people-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

surfe-people-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Surfe People API
  version: '2.0'
  description: 'The Surfe API (formerly Leadjet) provides B2B people and company search plus enrichment. It returns verified professional emails and mobile phone numbers, company firmographics, and lookalike account recommendations. Bulk enrichment is asynchronous: start a job with POST and either poll the GET job endpoint or receive a webhook callback. All requests are authenticated with a Bearer API key managed from the Surfe dashboard.'
  contact:
    name: Surfe API Support
    url: https://developers.surfe.com/
  x-former-name: Leadjet
servers:
- url: https://api.surfe.com/v2
  description: Surfe API v2 production base URL
security:
- bearerAuth: []
tags:
- name: People
  description: Search and enrich individual contacts.
paths:
  /people/search:
    post:
      tags:
      - People
      summary: Search people
      description: Search for people by persona filters (job titles, seniorities, departments) and company filters (industry, headcount, location). Job titles are expanded automatically with acronym and semantic matching. Results are paged with nextPageToken.
      operationId: searchPeople
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleSearchRequest'
      responses:
        '200':
          description: Matching people.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeopleSearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'
  /people/enrich:
    post:
      tags:
      - People
      summary: Enrich people (start)
      description: Start an asynchronous bulk enrichment job for up to 10,000 people. Each person is identified by a LinkedIn URL, or by first name + last name + company name or domain. Returns an enrichment ID for polling or a webhook callback.
      operationId: startPeopleEnrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleEnrichmentRequest'
      responses:
        '202':
          description: Enrichment job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentJobAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimited'
  /people/enrich/{id}:
    get:
      tags:
      - People
      summary: Enrich people (get)
      description: Retrieve the status and results of a people enrichment job by ID. Poll until status is COMPLETED, or use a webhook to be notified.
      operationId: getPeopleEnrichment
      parameters:
      - name: id
        in: path
        required: true
        description: The enrichment job ID returned by the start operation.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Enrichment job status and enriched people.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeopleEnrichmentResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /people/find-by-email:
    post:
      tags:
      - People
      summary: Find people by email
      description: Enrich people directly from a list of email addresses, returning the matched person profile and firmographics where available.
      operationId: findPeopleByEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: Email addresses to enrich.
      responses:
        '200':
          description: Matched people.
          content:
            application/json:
              schema:
                type: object
                properties:
                  people:
                    type: array
                    items:
                      $ref: '#/components/schemas/EnrichedPerson'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    RateLimited:
      description: Too many requests. The API allows up to 10 requests per second with short bursts to 20, plus a daily request quota.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientCredits:
      description: Not enough credits to complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource or job not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PeopleSearchResponse:
      type: object
      properties:
        people:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        total:
          type: integer
        nextPageToken:
          type: string
    JobHistoryEntry:
      type: object
      properties:
        companyName:
          type: string
        companyDomain:
          type: string
        jobTitle:
          type: string
        startDate:
          type: string
        endDate:
          type: string
    PeopleEnrichmentRequest:
      type: object
      required:
      - people
      - include
      properties:
        people:
          type: array
          minItems: 1
          maxItems: 10000
          description: People to enrich. Each entry needs at least a linkedinUrl, or firstName + lastName + companyName or companyDomain.
          items:
            $ref: '#/components/schemas/PersonInput'
        include:
          type: object
          description: Which fields to retrieve.
          properties:
            email:
              type: boolean
            mobile:
              type: boolean
            linkedInUrl:
              type: boolean
            jobHistory:
              type: boolean
        enrichmentOptions:
          type: object
          properties:
            acceptedEmailType:
              type: string
              enum:
              - professional
              - personal
            skipMobileEnrichmentIfNoEmailFound:
              type: boolean
        notificationOptions:
          type: object
          properties:
            webhookUrl:
              type: string
              format: uri
    EnrichmentJobAccepted:
      type: object
      properties:
        enrichmentID:
          type: string
          format: uuid
        enrichmentCallbackURL:
          type: string
          format: uri
        message:
          type: string
          description: Estimated completion time.
    Person:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        jobTitle:
          type: string
        seniorities:
          type: array
          items:
            type: string
        departments:
          type: array
          items:
            type: string
        companyName:
          type: string
        companyDomain:
          type: string
        country:
          type: string
        linkedInUrl:
          type: string
        externalID:
          type: string
    PeopleFilters:
      type: object
      description: Person-based filters.
      properties:
        jobTitles:
          type: array
          items:
            type: string
          description: Job titles to match. Titles are expanded automatically with bidirectional acronym and semantic matching.
        seniorities:
          type: array
          items:
            type: string
        departments:
          type: array
          items:
            type: string
        countries:
          type: array
          items:
            type: string
    EnrichedPerson:
      allOf:
      - $ref: '#/components/schemas/Person'
      - type: object
        properties:
          emails:
            type: array
            items:
              $ref: '#/components/schemas/EmailRecord'
          mobilePhones:
            type: array
            items:
              $ref: '#/components/schemas/PhoneRecord'
          jobHistory:
            type: array
            items:
              $ref: '#/components/schemas/JobHistoryEntry'
          status:
            type: string
    CompanyFilters:
      type: object
      description: Company-based filters.
      properties:
        industries:
          type: array
          items:
            type: string
        employeeCount:
          $ref: '#/components/schemas/Range'
        revenue:
          $ref: '#/components/schemas/Range'
        countries:
          type: array
          items:
            type: string
        domains:
          type: array
          items:
            type: string
        keywords:
          type: array
          items:
            type: string
    Range:
      type: object
      properties:
        from:
          type: integer
        to:
          type: integer
    PeopleEnrichmentResult:
      type: object
      properties:
        enrichmentID:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatus'
        percentCompleted:
          type: integer
        people:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedPerson'
    EmailRecord:
      type: object
      properties:
        email:
          type: string
          format: email
        type:
          type: string
          enum:
          - professional
          - personal
        validationStatus:
          type: string
    PeopleSearchRequest:
      type: object
      required:
      - limit
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 200
          description: Maximum results per page.
        people:
          $ref: '#/components/schemas/PeopleFilters'
        companies:
          $ref: '#/components/schemas/CompanyFilters'
        peoplePerCompany:
          type: integer
          minimum: 1
          maximum: 5
          description: Maximum results returned per company.
        pageToken:
          type: string
          description: Pagination token from a previous response.
    PhoneRecord:
      type: object
      properties:
        mobilePhone:
          type: string
        confidenceScore:
          type: number
    JobStatus:
      type: string
      enum:
      - PENDING
      - IN_PROGRESS
      - COMPLETED
      - FAILED
    PersonInput:
      type: object
      properties:
        linkedinUrl:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        companyName:
          type: string
        companyDomain:
          type: string
        externalID:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Surfe API key issued from the Surfe dashboard, sent as `Authorization: Bearer {api-key}`.'