Enrich People

Fetches each profile live from LinkedIn: current and past positions, education, skills, languages and certifications. Send up to 25 URLs per call; each gets its own entry in results, in the order you sent them.

A profile that does not exist, or a URL that is not a LinkedIn profile, costs nothing. With include_email, we also look for a work email (name and company domain, checked over SMTP) — if we only find a personal address, you get that one instead.

Calls with many profiles take a while: count on about 5 seconds per profile, spread over parallel lookups. Set your HTTP timeout to at least 120 seconds. A found profile costs 2 credits. A found email adds 10. This endpoint has no phone field. A work email together with a phone number is the in-app contact reveal (40 credits) and is not a call on this API.

Authentication

Send Authorization: Bearer gtk_…. This People endpoint answers when your key is valid. max_credits, and person_ids on enrich, are accepted only when the Signals API is open for your organization. Otherwise those fields are unknown and the call is 400.

Body parameters

• profile_urls string[] — 1 to 25 LinkedIn profile URLs, e.g. https://www.linkedin.com/in/jane-example. The member-id form that Search People returns works too. Send this or person_ids, not both.
• person_ids string[] — 1 to 25 person ids (per_…) from an earlier response of your organization, kept for 30 days. An id this organization does not know is not_found and costs nothing. Accepted when the Signals API is open for your organization.
• include_email boolean — Also look for an email address. Adds 10 credits per address found. Defaults to false. This endpoint does not look up a phone number.
• max_credits integer — Stop before the call costs more than this. A profile that would not fit is not looked up. Below the cost of one profile the call is 402 max_credits_exceeded and nothing is looked up. Accepted when the Signals API is open for your organization.

Response

• results object[] — One entry per URL you sent, in the same order.
• results[].input string — The URL as you sent it.
• results[].status string — matched, not_found (no such profile), invalid_url (not a LinkedIn profile URL) or error (lookup failed; retry later). One of: matched, not_found, invalid_url, error.
• results[].person object | null — The profile when the status is matched, otherwise null. See the fields below.
• person.linkedin_url string — Public profile URL.
• person.linkedin_id string | null — LinkedIn member id.
• person.public_identifier string | null — The slug in the profile URL.
• person.first_name / last_name / full_name string | null — Name.
• person.headline string | null — Headline under the name.
• person.about string | null — The About section.
• person.location object — text as LinkedIn shows it, plus city, state, country and country_code (ISO 3166-1 alpha-2) when known.
• person.picture_url string | null — Profile photo. LinkedIn photo URLs expire after a few weeks.
• person.connections_count / follower_count integer | null — Network size.
• person.open_to_work / hiring / premium boolean | null — Profile badges.
• person.current_positions object[] — The entries of experience that are still ongoing.
• person.experience object[] — Positions, newest first: title, company_name, company_linkedin_url, location, employment_type, workplace_type, start_date and end_date (year, month; end_date is null while ongoing), is_current, duration, description.
• person.education object[] — school_name, school_linkedin_url, degree, field_of_study, start_date, end_date, description.
• person.skills string[] — Skills, top skills first.
• person.languages object[] — name and proficiency.
• person.certifications object[] — name, issued_by, issued_at.
• person.email object | null — Only with include_email: address, type (work or personal), deliverable and catch_all (booleans from the SMTP check; null when unknown) and quality_score. Null when nothing was found.
• credits_used integer — Credits this call used.

Credits

2 credits per profile found, +10 per email found Errors and empty lookups are free. A call that spent credits puts that number in credits_used, in X-Credits-Used and in X-Credits-Charged. When the wallet can be read, the response also sends X-Credits-Remaining.

Errors

• 400 invalid_request — The body is not valid JSON, a field is unknown or has the wrong type, or a value is not allowed.
• 401 authentication_error — The Authorization header is missing, or the key is unknown or revoked.
• 403 permission_error — API access is not part of your plan, or your account is suspended.
• 429 rate_limit_error — More than 60 requests per minute, or more than 3 at the same time, on one key. Wait for the Retry-After header.
• 429 daily_limit_reached — The request could take your organization over its daily credit limit. The limit resets at midnight (Europe/Brussels).
• 502 upstream_error — The data source did not answer. Retry later.
• 503 service_unavailable — The API is temporarily unavailable. Retry later.
• 500 internal_error — Something went wrong on our side.
• 402 max_credits_exceeded — Only when the Signals API is open and max_credits is below one row.

Example

cURL

curl -X POST "https://foundermcp.dev/api/v1/person/enrich" \
  -H "Authorization: Bearer $FOUNDERMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_urls": [
      "https://www.linkedin.com/in/jane-example",
      "https://www.linkedin.com/in/does-not-exist-123"
    ],
    "include_email": true
  }'

JavaScript

const response = await fetch('https://foundermcp.dev/api/v1/person/enrich', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUNDERMCP_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "profile_urls": [
      "https://www.linkedin.com/in/jane-example",
      "https://www.linkedin.com/in/does-not-exist-123"
    ],
    "include_email": true
  })
});
const body = await response.json();

Python

import json
import os
import urllib.request

payload = {
  "profile_urls": [
    "https://www.linkedin.com/in/jane-example",
    "https://www.linkedin.com/in/does-not-exist-123"
  ],
  "include_email": true
}

request = urllib.request.Request(
    "https://foundermcp.dev/api/v1/person/enrich",
    headers={
    "Authorization": f"Bearer {os.environ['FOUNDERMCP_API_KEY']}",
    "Content-Type": "application/json"
    },
    data=json.dumps(payload).encode(),
    method="POST",
)
with urllib.request.urlopen(request) as response:
    body = json.load(response)

Example response

{
  "results": [
    {
      "input": "https://www.linkedin.com/in/jane-example",
      "status": "matched",
      "person": {
        "linkedin_url": "https://www.linkedin.com/in/jane-example",
        "linkedin_id": "ACwAAExample123",
        "public_identifier": "jane-example",
        "first_name": "Jane",
        "last_name": "Example",
        "full_name": "Jane Example",
        "headline": "CFO at Acme Analytics",
        "about": null,
        "location": {
          "text": "Ghent, Flemish Region, Belgium",
          "city": "Ghent",
          "state": "Flemish Region",
          "country": "Belgium",
          "country_code": "BE"
        },
        "picture_url": null,
        "connections_count": 500,
        "follower_count": 1204,
        "open_to_work": false,
        "hiring": false,
        "premium": true,
        "current_positions": [
          {
            "title": "Chief Financial Officer",
            "company_name": "Acme Analytics",
            "company_linkedin_url": "https://www.linkedin.com/company/acme-analytics",
            "location": "Ghent, Belgium",
            "employment_type": "Full-time",
            "workplace_type": "Hybrid",
            "start_date": {
              "year": 2026,
              "month": 7
            },
            "end_date": null,
            "is_current": true,
            "duration": "3 mos",
            "description": null
          }
        ],
        "experience": [
          {
            "title": "Chief Financial Officer",
            "company_name": "Acme Analytics",
            "company_linkedin_url": "https://www.linkedin.com/company/acme-analytics",
            "location": "Ghent, Belgium",
            "employment_type": "Full-time",
            "workplace_type": "Hybrid",
            "start_date": {
              "year": 2026,
              "month": 7
            },
            "end_date": null,
            "is_current": true,
            "duration": "3 mos",
            "description": null
          }
        ],
        "education": [
          {
            "school_name": "Ghent University",
            "school_linkedin_url": null,
            "degree": "Master of Science",
            "field_of_study": "Business Economics",
            "start_date": {
              "year": 2008,
              "month": null
            },
            "end_date": {
              "year": 2012,
              "month": null
            },
            "description": null
          }
        ],
        "skills": [
          "Financial Planning",
          "M&A"
        ],
        "languages": [
          {
            "name": "Dutch",
            "proficiency": "Native or bilingual proficiency"
          }
        ],
        "certifications": [],
        "email": {
          "address": "jane@acme-analytics.example",
          "type": "work",
          "deliverable": true,
          "catch_all": false,
          "quality_score": 95
        }
      }
    },
    {
      "input": "https://www.linkedin.com/in/does-not-exist-123",
      "status": "not_found",
      "person": null
    }
  ],
  "credits_used": 12
}