Search people

curl --request POST \
  --url https://mcp.enricho.co/api/directory/people/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "country_code": "GB",
  "job_title": [
    "engineer",
    "developer"
  ],
  "preview": true
}
'

{
  "success": true,
  "result": {
    "results": [
      {
        "person_id": "<string>",
        "first_name": "<string>",
        "middle_name": "<string>",
        "last_name": "<string>",
        "full_name": "<string>",
        "email": "<string>",
        "alternate_email": "<string>",
        "email_type": "<string>",
        "phone": "<string>",
        "alternate_phone": "<string>",
        "gender": "<string>",
        "age": 123,
        "birth_year": 123,
        "birth_month": 123,
        "birth_date": 123,
        "estimated_income": "<string>",
        "income_min": 123,
        "income_max": 123,
        "job_title": "<string>",
        "seniority": "<string>",
        "role": "<string>",
        "industry": "<string>",
        "skills": [
          "<string>"
        ],
        "interests": [
          "<string>"
        ],
        "years_experience": 123,
        "address": "<string>",
        "city": "<string>",
        "region": "<string>",
        "zip_code": "<string>",
        "country": "<string>",
        "country_code": "<string>",
        "continent": "<string>",
        "countries": [
          "<string>"
        ],
        "linkedin_url": "<string>",
        "linkedin_connections": 123,
        "x_url": "<string>",
        "instagram_url": "<string>",
        "tiktok_url": "<string>",
        "facebook_url": "<string>",
        "github_url": "<string>",
        "company": {
          "company_id": "<string>",
          "name": "<string>",
          "domain": "<string>",
          "industry": "<string>",
          "employee_size_band": "<string>",
          "size_min": 123,
          "size_max": 123,
          "website": "<string>",
          "phone": "<string>",
          "address": "<string>",
          "country": "<string>",
          "country_code": "<string>",
          "linkedin_url": "<string>",
          "x_url": "<string>",
          "facebook_url": "<string>"
        },
        "extras": {},
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "next_cursor": "<string>",
    "has_more": true,
    "credits_used": 50
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

POST

api

directory

people

curl --request POST \
  --url https://mcp.enricho.co/api/directory/people/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "country_code": "GB",
  "job_title": [
    "engineer",
    "developer"
  ],
  "preview": true
}
'

{
  "success": true,
  "result": {
    "results": [
      {
        "person_id": "<string>",
        "first_name": "<string>",
        "middle_name": "<string>",
        "last_name": "<string>",
        "full_name": "<string>",
        "email": "<string>",
        "alternate_email": "<string>",
        "email_type": "<string>",
        "phone": "<string>",
        "alternate_phone": "<string>",
        "gender": "<string>",
        "age": 123,
        "birth_year": 123,
        "birth_month": 123,
        "birth_date": 123,
        "estimated_income": "<string>",
        "income_min": 123,
        "income_max": 123,
        "job_title": "<string>",
        "seniority": "<string>",
        "role": "<string>",
        "industry": "<string>",
        "skills": [
          "<string>"
        ],
        "interests": [
          "<string>"
        ],
        "years_experience": 123,
        "address": "<string>",
        "city": "<string>",
        "region": "<string>",
        "zip_code": "<string>",
        "country": "<string>",
        "country_code": "<string>",
        "continent": "<string>",
        "countries": [
          "<string>"
        ],
        "linkedin_url": "<string>",
        "linkedin_connections": 123,
        "x_url": "<string>",
        "instagram_url": "<string>",
        "tiktok_url": "<string>",
        "facebook_url": "<string>",
        "github_url": "<string>",
        "company": {
          "company_id": "<string>",
          "name": "<string>",
          "domain": "<string>",
          "industry": "<string>",
          "employee_size_band": "<string>",
          "size_min": 123,
          "size_max": 123,
          "website": "<string>",
          "phone": "<string>",
          "address": "<string>",
          "country": "<string>",
          "country_code": "<string>",
          "linkedin_url": "<string>",
          "x_url": "<string>",
          "facebook_url": "<string>"
        },
        "extras": {},
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "next_cursor": "<string>",
    "has_more": true,
    "credits_used": 50
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

{
  "success": false,
  "result": {
    "code": "<string>"
  },
  "message": "<string>"
}

All filters are optional; {} is an unfiltered paid full search. Different fields combine with AND; list values combine with OR. person_id and linkedin_url resolve into one set of alternative person IDs. List filters accept one string or at most 100 strings. Each value and query is limited to 200 UTF-8 bytes before normalization.

Preview

curl -X POST 'https://mcp.enricho.co/api/directory/people/search' \
  -H 'Authorization: Bearer enr_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"country_code":"GB","job_title":["engineer","developer"],"preview":true}'

A preview returns at most 10 people for 0 credits. limit and cursor are ignored. has_more indicates additional matches, but next_cursor is empty and no count is exposed. Nonempty exclude_person_ids is rejected; exclude_company_domains allows at most 10 values. Daily preview caps apply. Preview fields: person_id, full_name, job_title, seniority, company_name, company_domain, industry, employee_size_band, city, country, country_code, has_email, has_phone, has_linkedin. Contact values and profile URLs are not returned. Flags describe cleaned contact presence, not verification or deliverability.

Full retrieval

Replace the ID with one from your own preview, or repeat its filters with preview: false:

curl -X POST 'https://mcp.enricho.co/api/directory/people/search' \
  -H 'Authorization: Bearer enr_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"person_id":["PERSON_ID_FROM_PREVIEW"],"preview":false,"limit":1}'

Continuation example (only use a cursor from a full search with the same filters):

curl -X POST 'https://mcp.enricho.co/api/directory/people/search' \
  -H 'Authorization: Bearer enr_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"company_domain":"example.com","limit":5,"cursor":"NEXT_CURSOR_FROM_PREVIOUS_RESPONSE"}'

Full pages cost 1 credit per returned person, including repeats; empty pages cost 0. Default page size is 20, maximum 100. Insufficient balance for the whole page returns 402 without records or a debit. Pagination and retry precautions apply.

Matching

email: exact primary or alternate email, lowercased.
full_name, company_name, job_title, role: case-insensitive substrings; role underscores normalize to spaces.
industry: substring in either person or employer industry.
city, country_code, company_id, company_domain: exact after normalization. Country codes are uppercased; domains lowercased without schemes, paths or leading www.. IDs remain case-sensitive.
linkedin_url: a LinkedIn profile /in/<slug> URL, converted to an ID; company URLs are invalid.
seniority: stored level or title-derived matches, including c_suite, vp, director, head, manager, founder, owner, partner, senior, entry. Aliases include executive, vice president and junior. Unknown values can match their own title words; this is not a strict enum.
employee_size_band: stored employer-size label, not a numeric range. skill: any matching stored skill, lowercased.
has_email, has_phone, has_linkedin: true restricts stored contact presence; false does not mean missing. Read-time cleaning can remove an invalid stored phone even if the presence filter matched.
exclude_person_ids, exclude_company_domains: exclusion lists; full searches accept up to 100 each.
query: every retained term must match searchable name, email, title, role, seniority, employer, industry or location text. Terms are lowercased, common stop words removed, and at most 10 distinct terms retained. This is not Boolean query syntax.

Full record fields

Expand the response schema for every exact field and nested employer shape. Full records include names; primary/alternate email and phone; email type; available demographic and income fields; role, seniority, skills, interests and experience; address/location; social URLs; company; extras; and updated_at. Unavailable strings are "", nullable numbers are null, arrays may be [], and extras is {} when absent. company is null if no company ID is associated. Extra keys vary by record. Do not assume unavailable fields are omitted or that contacts are verified; updated_at is an update timestamp, not a verification timestamp.

Authorizations

Authorization

string

header

required

Enricho API key (enr_...)

Body

application/json

Send JSON with Content-Type: application/json.

All fields are optional; {} searches without filters. Different filter fields combine with AND; multiple values in a filter combine with OR. Record-ID exclusions are full-search only.

person_id

Exact person IDs from search results. Values are case-sensitive. Combined with linkedin_url as alternative person IDs. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

linkedin_url

LinkedIn profile URLs with /in/. Converted to person IDs and combined with person_id as alternatives. Company URLs are invalid. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

Exact primary or alternate email matches, normalized to lowercase. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

full_name

Case-insensitive full-name substring matches. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

company_name

Case-insensitive employer-name substring matches. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

job_title

Case-insensitive job-title substring matches. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

seniority

Stored seniority or inferred title-level matches. Common levels: c_suite, vp, director, head, manager, founder, owner, partner, senior, entry. Aliases include c-level, executive, vice president, co-founder, junior and intern. Unknown values match their own title words. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

role

Case-insensitive role substring matches; underscores normalize to spaces. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

country_code

Country codes, uppercased (for example GB or US). Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

city

Case-insensitive exact city matches. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

company_id

Exact employer company IDs, case-sensitive. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

company_domain

Exact employer domains, lowercased; URL schemes, paths and leading www. are removed. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

industry

Case-insensitive substring matches in the person industry or employer industry. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

employee_size_band

Stored employer employee-size band (for example 1-10 or 51-200), not a numeric range comparison. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

skill

Any matching skill in the comma-separated skill list, normalized to lowercase. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

exclude_company_domains

Exclude these normalized employer domains. Full search: up to 100 values; preview: up to 10. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

exclude_person_ids

Exclude exact person IDs. Only available in full searches; any nonempty list is rejected in preview. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization.

Maximum string length: 200

query

string

Free text, limited to 200 UTF-8 bytes. Up to 10 distinct lowercased terms after splitting on whitespace, commas and semicolons and removing common stop words. Every retained term must match a searchable text field; this is not a Boolean query language.

Maximum string length: 200

has_email

boolean

default:false

Require a stored primary email. false or omission adds no restriction; it does not search for missing data. Stored presence does not guarantee a valid cleaned value.

has_phone

boolean

default:false

Require a stored primary or alternate phone. false or omission adds no restriction; it does not search for missing data. Stored presence does not guarantee a valid cleaned value.

has_linkedin

boolean

default:false

Require a stored LinkedIn profile URL. false or omission adds no restriction; it does not search for missing data. Stored presence does not guarantee a valid cleaned value.

preview

boolean

default:false

true returns a free first-page preview of up to 10 records. limit and cursor are ignored; previews cannot be paginated. false returns full records at 1 credit each.

limit

integer

default:20

Full search page size, 1–100. Omitted or 0 uses 20. Negative values or values above 100 return 400. Ignored in preview.

Required range: 0 <= x <= 100

cursor

string

default:""

Opaque next_cursor from a previous full search with the same filters. Omit or use an empty string for the first page. Ignored in preview.

Response

Success envelope.

success

boolean

required

result

object

required

No total_estimate or total_capped fields are returned by public search.

Option 1
Option 2

Show child attributes

message

string

required

Essentials

Directory

Billing and usage

Preview

Full retrieval

Matching

Full record fields

Authorizations

Body

Response

​Preview

​Full retrieval

​Matching

​Full record fields

Authorizations

Body

Response

Preview

Full retrieval

Matching

Full record fields