Person Enrichment - Crustdata Docs

The Person Enrich API takes a profile URL and returns a rich person profile. This page covers the basics (your first enrichment and the response shape) plus worked example recipes. For the request/response schema and errors, see Enrich reference. Every request goes to the same endpoint:

POST https://api.crustdata.com/person/enrich

Replace YOUR_API_KEY in each example with your actual API key. All requests require the x-api-version: 2025-11-01 header.

Request body

Parameter	Type	Required	Description
`professional_network_profile_urls`	array	Yes	Profile URLs to enrich. Max 25 per request.
`fields`	array	No	Specific field paths or section groups to include.

Response body

The response is a top-level array. Each entry corresponds to one input identifier.

Field	Type	Description
`matched_on`	string	The input profile URL
`match_type`	string	`professional_network_profile_url`
`matches`	array	Candidate matches. Empty for no-match inputs.
`matches[].confidence_score`	number	0 to 1. Higher is better. `1.0` is common for direct URL lookups.
`matches[].person_data`	object	Full enriched profile.

Rate limits and pricing

Pricing: Base profile is 1 credit. Developer platform data adds 1 credit. Maximum: 2 credits per profile.

Need email addresses or phone numbers? Use Contact Enrich.

Reference

Request parameters, response fields, valid fields values, person_data sections, advanced flags, errors.

Your first enrichment: look up a profile

The simplest enrichment takes a single profile URL and returns the person’s cached profile. Pass the URL in the professional_network_profile_urls array.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": [
      "https://www.linkedin.com/in/abhilashchowdhary/"
    ]
  }'

[
    {
        "matched_on": "https://www.linkedin.com/in/abhilashchowdhary/",
        "match_type": "professional_network_profile_url",
        "matches": [
            {
                "confidence_score": 1.0,
                "person_data": {
                    "basic_profile": {
                        "name": "Abhilash Chowdhary",
                        "headline": "Co-founder at Crustdata (YC F24) | Real-time B2B data for AI agents",
                        "current_title": "Co-Founder & CEO",
                        "summary": "Love building things. A software engineer with vast experience in shipping products spanning robotics, web technologies and quantitative finance.",
                        "location": {
                            "city": null,
                            "continent": null,
                            "country": null,
                            "raw": "San Francisco, California, United States",
                            "state": null
                        },
                        "languages": ["English", "Hindi"],
                        "last_updated": "2026-03-03T17:09:31.949863Z"
                    },
                    "crustdata_person_id": 1068035,
                    "social_handles": {
                        "twitter_identifier": {}
                    }
                }
            }
        ]
    }
]

Response trimmed for clarity. The full response can include employment history, education, skills, and developer platform profiles when available.

Understanding the response

The Enrich API returns an array — one entry per identifier you submitted. Each entry has three fields:

matched_on — the profile URL you submitted.
match_type — professional_network_profile_url.
matches — an array of candidate profiles. Each match includes a confidence_score (0 to 1) and the full person_data object.

For profile URL lookups, you will typically get exactly one match with a confidence_score of 1.0, because the URL is a direct identifier.

Need fresh data from the web?

If the cached enrich response is missing a recent update or you need real-time retrieval from the web, use Person Live Enrich. That endpoint is designed for fresh profile retrieval when cached enrich is not enough.

Examples

Worked recipes you can copy, paste, and adapt.

Selecting fields: education, employers, and more

By default, /person/enrich returns only the basic_profile and social_handles sections. Employment history, education, and skills are not returned unless you request them with the fields parameter.

Request any of these sections (or dot-paths within them) in fields:

Section	Returns
`experience`	Employment history — current and past roles, each with company, `crustdata_company_id`, title, and dates
`education`	Schools, degrees, and fields of study
`skills`	Professional skills
`professional_network`	Connections, followers, and profile metadata
`dev_platform_profiles`	Developer platform context (extra credit)
`certifications`, `honors`	Certifications and awards (gated — require field-level permission on your key)

experience, education, skills, and professional_network are part of the base profile (1 credit) — requesting them adds no extra credits. dev_platform_profiles costs more. See Pricing and the full field catalog.

Employment history — all current and past employers

Pass experience to get each role’s company, crustdata_company_id, title, and dates.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile", "experience"]
  }'

[
  {
    "matched_on": "https://www.linkedin.com/in/dvdhsu/",
    "match_type": "professional_network_profile_url",
    "matches": [
      {
        "confidence_score": 1.0,
        "person_data": {
          "basic_profile": { "name": "David Hsu", "current_title": "Founder, CEO" },
          "experience": {
            "employment_details": {
              "current": [
                {
                  "name": "Retool",
                  "title": "Founder, CEO",
                  "crustdata_company_id": 633593,
                  "start_date": "2017-01-01T00:00:00+00:00"
                }
              ],
              "past": []
            }
          }
        }
      }
    ]
  }
]

Education background

Pass education for each school, degree, and field of study.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile", "education"]
  }'

{
  "education": {
    "schools": [
      {
        "school": "University of Oxford",
        "degree": "Bachelor of Arts (B.A.)",
        "field_of_study": "Philosophy and Computer Science"
      }
    ]
  }
}

Request all available fields

Name every section you want in one call. experience, education, skills, and professional_network are part of the base profile (no extra credits). dev_platform_profiles adds a credit. certifications and honors are omitted here — they require field-level permission on your key and otherwise return an error (see the gated example below).

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": [
      "basic_profile",
      "professional_network",
      "experience",
      "education",
      "skills",
      "social_handles",
      "dev_platform_profiles"
    ]
  }'

{
  "basic_profile": { "name": "David Hsu", "current_title": "Founder, CEO" },
  "professional_network": { "connections": 700, "followers": 14319, "joined_date": "2007-12-01T00:00:00+00:00", "open_to_cards": [] },
  "experience": {
    "employment_details": {
      "current": [
        { "name": "Retool", "title": "Founder, CEO", "crustdata_company_id": 633593 }
      ],
      "past": []
    }
  },
  "education": {
    "schools": [
      { "school": "University of Oxford", "degree": "Bachelor of Arts (B.A.)", "field_of_study": "Philosophy and Computer Science" }
    ]
  },
  "skills": { "professional_network_skills": [] },
  "social_handles": {
    "professional_network_identifier": { "profile_url": "https://www.linkedin.com/in/dvdhsu" }
  },
  "dev_platform_profiles": []
}

To also include certifications and honors, your API key needs field-level permission — contact Crustdata to enable them. skills and dev_platform_profiles may be empty for some profiles.

Specific nested fields only

Use dot-paths to pull just the sub-fields you need instead of whole sections.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile.name", "experience.employment_details.current.title", "education.schools.degree"]
  }'

Get the profile URLs — vanity and permanent (URN)

Request the social_handles section to get the person’s canonical profile URLs — useful for keying records or linking out to the profile.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile.name", "social_handles"]
  }'

[
    {
        "matched_on": "https://www.linkedin.com/in/dvdhsu/",
        "match_type": "professional_network_profile_url",
        "matches": [
            {
                "confidence_score": 1.0,
                "person_data": {
                    "basic_profile": { "name": "David Hsu" },
                    "social_handles": {
                        "professional_network_identifier": {
                            "profile_url": "https://www.linkedin.com/in/dvdhsu",
                            "urn_url": "https://www.linkedin.com/in/ACoAAAEnBBoBUwCVyafB-XsEBTeHaFN8ScMKh6U"
                        },
                        "dev_platform_identifier": { "profile_url": null },
                        "twitter_identifier": { "slug": "" }
                    }
                }
            }
        ]
    }
]

profile_url — the canonical vanity URL. The slug can change if the person edits it.
urn_url — the permanent URN-based URL, which never changes. Use it (or crustdata_person_id) as a stable per-person key.

urn_url requires field-level permission on your API key and is absent from the response by default — contact support to enable it. Both URL forms are accepted as input identifiers in professional_network_profile_urls.

Preview mode — basic profile at 0 credits

Set preview: true to get a lightweight response at 0 credits: the crustdata_person_id, basic_profile, social_handles.professional_network_identifier, and the person’s connection count and profile picture. Any fields you pass are ignored in preview mode, and preview cannot be combined with enrich_realtime.

Request

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "preview": true
  }'

Preview is enterprise only and must be enabled for your account — contact the Crustdata team to turn it on. Without it, the API returns 400 invalid_request with the message Preview feature is not available for your account. Please reach out to Crustdata team.

Developer platform profile (extra credit)

dev_platform_profiles returns developer platform context (repos, orgs, activity) and adds +1 credit.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile", "dev_platform_profiles"]
  }'

Starting from a dev-platform URL instead? /person/enrich does not accept dev-platform URLs as identifiers (the legacy endpoint did). Use the Dev Platform API — POST /dev_platform/enrich takes profile_url: "https://github.com/<handle>" or a crustdata_person_id directly.

Certifications and honors (gated — needs field permission)

certifications and honors require field-level permission on your API key. Without it, the request returns a permission error — contact Crustdata to enable them for your key.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile", "certifications", "honors"]
  }'

More recipes

Handle no-match results

Not every identifier will resolve to a person. When there is no match, the matches array is empty.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": [
      "https://www.linkedin.com/in/no-such-profile/"
    ]
  }'

[
    {
        "matched_on": "https://www.linkedin.com/in/no-such-profile/",
        "match_type": "professional_network_profile_url",
        "matches": []
    }
]

You still get a response entry for the identifier — matched_on tells you which input had no match. This makes it easy to track which lookups succeeded and which need a different approach.

Batch enrichment — look up multiple people at once

You can enrich up to 25 identifiers in a single request. The response returns one entry per identifier, in the same order you submitted them.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": [
      "https://www.linkedin.com/in/dvdhsu/",
      "https://www.linkedin.com/in/abhilashchowdhary/"
    ]
  }'

[
    {
        "matched_on": "https://www.linkedin.com/in/dvdhsu/",
        "match_type": "professional_network_profile_url",
        "matches": [
            {
                "confidence_score": 1.0,
                "person_data": {
                    "basic_profile": {
                        "name": "David Hsu",
                        "headline": "Founder, CEO @ Retool",
                        "current_title": "Founder, CEO",
                        "location": {
                            "city": "San Francisco",
                            "state": "California",
                            "country": "United States",
                            "continent": "North America",
                            "raw": "San Francisco Bay Area"
                        }
                    },
                    "social_handles": {
                        "professional_network_identifier": {
                            "profile_url": "https://www.linkedin.com/in/dvdhsu"
                        }
                    }
                }
            }
        ]
    },
    {
        "matched_on": "https://www.linkedin.com/in/abhilashchowdhary/",
        "match_type": "professional_network_profile_url",
        "matches": [
            {
                "confidence_score": 1.0,
                "person_data": {
                    "basic_profile": {
                        "name": "Abhilash Chowdhary",
                        "headline": "Co-founder at Crustdata (YC F24) | Real-time B2B data for AI agents",
                        "current_title": "Co-Founder & CEO",
                        "location": {
                            "city": "San Francisco",
                            "state": "California",
                            "country": "United States of America",
                            "continent": "North America",
                            "raw": "San Francisco, California, United States"
                        }
                    },
                    "social_handles": {
                        "professional_network_identifier": {
                            "profile_url": "https://www.linkedin.com/in/abhilashchowdhary"
                        }
                    }
                }
            }
        ]
    }
]

Response trimmed for clarity.

Batch enrichment tips

The maximum batch size is 25 identifiers per request.
Each entry in the response corresponds to the input at the same position, so you can match results back to your input list by index.
If some identifiers fail to match, their matches array will be empty, but the request still succeeds for the others.

Workflow — Search then Enrich

The most powerful pattern combines Person Search with Person Enrich. Search finds people matching your criteria; Enrich gets the full profile for each match.Step 1: Search for decision-makers at a target company.

curl --request POST \
  --url https://api.crustdata.com/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        {
          "field": "experience.employment_details.current.company_name",
          "type": "in",
          "value": ["Retool"]
        },
        {
          "field": "experience.employment_details.current.title",
          "type": "(.)",
          "value": "VP|Director|Head of"
        }
      ]
    },
    "limit": 5
  }'

Step 2: Take the profile URLs from the search results and enrich them for full profiles.

curl --request POST \
  --url https://api.crustdata.com/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": [
      "https://www.linkedin.com/in/dvdhsu/",
      "https://www.linkedin.com/in/abhilashchowdhary/"
    ]
  }'

This two-step pattern is the foundation for most sales, recruiting, and research workflows. Search narrows the universe; Enrich fills in the details.

What to do next

Look up request/response details — see Enrich reference for parameters, valid fields values, person_data sections, and errors.
Search first, then enrich — use Person Search to find people by name, title, company, or location, then enrich the results.
Fetch fresh data from the web — use Person Live Enrich when cached enrich is not enough.

​Request body

​Response body

​Rate limits and pricing

Reference

​Your first enrichment: look up a profile

​Understanding the response

​Need fresh data from the web?

​Examples

​Selecting fields: education, employers, and more

​More recipes

​What to do next

Request body

Response body

Rate limits and pricing

Your first enrichment: look up a profile

Understanding the response

Need fresh data from the web?

Examples

Selecting fields: education, employers, and more

More recipes

What to do next