Enrich Person Data

POST https://api.onfire.ai/data-access-api/v1/person/enrich

Retrieve professional profile data, persona classifications, contact information, and company details for one or more persons.

Identification strategies

Each person can be identified by one of:

LinkedIn URL — direct lookup, fastest.
Work email — resolved via the Matchbox identity graph.
Full name + company domain — resolved via Matchbox.
Full name + company name — resolved via Matchbox when only the company name is known.
First name + last name + company domain or company name — resolved via Matchbox; names are joined internally.
All combined — highest-confidence resolution.

See PersonIdentifier for the full schema and validation rules, or the inline table below.

PersonIdentifier (inline) {#personidentifier-inline}

Each entry in persons is a PersonIdentifier. You must supply at least one valid combination from the resolution strategies above.

Field	Type	Description
`linkedin_url`	`string`	LinkedIn profile URL — e.g. `"linkedin.com/in/scott-goldman-1736a0"`. Direct lookup; no identity resolution step. The `https://www.` prefix is optional.
`work_email`	`string`	Professional / work email — e.g. `"scott.goldman@bankofamerica.com"`. Resolved via the Matchbox identity graph. Can be combined with name and company fields for higher accuracy.
`full_name`	`string`	Full name as on a professional profile — e.g. `"Scott Goldman"`. Must be paired with `company_domain` or `company_name`.
`first_name`	`string`	Given name — e.g. `"Scott"`. Must be provided together with `last_name` and at least one company identifier. Internally joined with `last_name` for Matchbox.
`last_name`	`string`	Family name — e.g. `"Goldman"`. Must be provided together with `first_name` and at least one company identifier.
`company_domain`	`string`	Website domain of the person’s current employer — e.g. `"bankofamerica.com"`. Bare domain only — no `https://` or `www.`.
`company_name`	`string`	Name of the person’s current employer — e.g. `"Bank of America"`. Can be used alongside or instead of `company_domain`.
`external_id`	`string`	A caller-supplied identifier (spreadsheet row, UUID, CRM record ID, etc.). Not used for matching. Echoed back unchanged in the response’s `identifier` object so you can correlate enrichment results with your source records.

When the person is resolved via Matchbox (i.e. anything other than linkedin_url), the response’s identifier object also includes a resolved_linkedin_url key showing which LinkedIn profile was matched.

Available person fields

Profile fields: contact_linkedin_url, contact_linkedin_id, first_name, last_name, full_name, job_title, company_linkedin_url, company_linkedin_id, company_website, contact_country, contact_region, location_locality, location_postal_code.

Query-membership fields (any name not in the profile list): returns 1 if the person matches or 0 if not — for example AWS, kubernetes, Splunk.

Optional enrichment features

include_personas — adds two extra fields to each result: a personas array of role/persona tags (e.g. "cto", "developer_software_engineer", "identity") and a seniority band. seniority is one of seniority_executive, seniority_director, seniority_teamlead, or seniority_ic. Consumes no additional credits.
include_contact_data — adds email and phone fields. Consumes additional credits.
enrich_company — adds a nested company object with firmographic / technographic data. Accepts true for all fields, or a list of field names for a subset.
allow_signals — retrieves intent signals for each person, matched by the person’s LinkedIn URL. Pass {} for all signals, or filter with start_time, end_time, and/or type.

Billing

Enrichment credits are consumed per person upfront and confirmed for each person who received Forschung profile / query data or contact data (email / phone). Contact data credits are consumed and confirmed separately when include_contact_data is enabled.

Request

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.
`X-Api-Key`	Yes	Your tenant API key.

Body

Field	Type	Required	Description
`persons`	`PersonIdentifier[]`	Yes	One or more person identifiers.
`fields`	`string[]`	No*	Data fields to return for each person.
`include_personas`	`boolean`	No	When `true`, adds `personas` (array of role/persona tags) and `seniority` (one of `seniority_executive`, `seniority_director`, `seniority_teamlead`, `seniority_ic`) to each result. Consumes no additional credits. Default `false`.
`include_contact_data`	`boolean`	No	When `true`, adds `email` and `phone` fields. Consumes additional credits. Default `false`.
`enrich_company`	`boolean \| string[]`	No	`false` (default): no company data. `true`: all available company fields. Array: only the specified company fields (same catalogue as `POST /v1/company/enrich`).
`allow_signals`	`AllowSignals`	No	When present, retrieves intent signals per person, matched by LinkedIn URL.

* At least one of fields, include_personas, include_contact_data, enrich_company, or allow_signals must be provided. Otherwise the API returns 400 NO_FIELDS_PROVIDED.

Example: lookup by LinkedIn URL, with selective company fields

curl -X POST "https://api.onfire.ai/data-access-api/v1/person/enrich" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "persons": [
      {
        "linkedin_url": "linkedin.com/in/scott-goldman-1736a0",
        "external_id": "sheet_row_42"
      }
    ],
    "fields": [
      "contact_linkedin_url",
      "first_name",
      "last_name",
      "full_name",
      "job_title"
    ],
    "enrich_company": [
      "name",
      "industry",
      "size",
      "location_country",
      "cto",
      "security"
    ],
    "allow_signals": {
      "start_time": "2024-09-01",
      "end_time": "2024-12-31",
      "type": "High Intent"
    }
  }'

Example: lookup by full name and company domain

curl -X POST "https://api.onfire.ai/data-access-api/v1/person/enrich" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "persons": [
      {
        "full_name": "Scott Goldman",
        "company_domain": "bankofamerica.com"
      }
    ],
    "fields": [
      "contact_linkedin_url",
      "first_name",
      "last_name",
      "full_name",
      "company_linkedin_url",
      "job_title",
      "contact_country",
      "contact_region",
      "location_locality",
      "location_postal_code"
    ],
    "include_personas": true,
    "enrich_company": true
  }'

Example: lookup by first name, last name, and company name

curl -X POST "https://api.onfire.ai/data-access-api/v1/person/enrich" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "persons": [
      {
        "first_name": "Scott",
        "last_name": "Goldman",
        "company_name": "Bank of America"
      }
    ],
    "fields": [
      "contact_linkedin_url",
      "first_name",
      "last_name",
      "full_name",
      "company_linkedin_url",
      "job_title"
    ],
    "include_personas": true,
    "enrich_company": true
  }'

Example: lookup by work email

curl -X POST "https://api.onfire.ai/data-access-api/v1/person/enrich" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "persons": [
      { "work_email": "scott.goldman@bankofamerica.com" }
    ],
    "fields": [
      "contact_linkedin_url",
      "first_name",
      "last_name",
      "full_name",
      "company_linkedin_url",
      "job_title"
    ],
    "include_personas": true,
    "enrich_company": true
  }'

Responses

200 — Success

Returns a results array with one EnrichmentResult per input person, in the same order as the request.

{
  "results": [
    {
      "identifier": {
        "linkedin_url": "linkedin.com/in/scott-goldman-1736a0",
        "external_id": "sheet_row_42"
      },
      "data": {
        "contact_linkedin_url": "linkedin.com/in/scott-goldman-1736a0",
        "first_name": "scott",
        "last_name": "goldman",
        "full_name": "scott goldman",
        "company_linkedin_url": "linkedin.com/company/bank-of-america",
        "job_title": "head of portfolio management & operational excellence chief technology officer",
        "contact_country": "united states",
        "contact_region": "florida",
        "location_locality": "deerfield beach",
        "location_postal_code": "33441",
        "personas": [
          "code_contributor",
          "cto",
          "developer_software_engineer",
          "developers",
          "identity"
        ],
        "seniority": "seniority_executive",
        "company": {
          "name": "bank of america",
          "industry": "banking",
          "size": "10001+",
          "employee_count": "232850",
          "website": "bankofamerica.com",
          "company_linkedin_url": "linkedin.com/company/bank-of-america",
          "location_country": "united states",
          "location_region": "north carolina",
          "location_locality": "charlotte",
          "location_postal_code": "28202",
          "cto": 20,
          "it": 1896,
          "security": 1468,
          "Splunk": 356,
          "SIEM": 399,
          "Jira": 628,
          "ServiceNow": 47,
          "CrowdStrike": 18,
          "Datadog": 28
        },
        "email": "scott.goldman@bofa.com",
        "phone": "+12127709693"
      },
      "matched": true
    }
  ]
}

When the person is found via identity resolution (e.g. work email or name + domain), the response’s identifier object is augmented with a resolved_linkedin_url key showing which LinkedIn profile was matched.

400 — Validation error

No persons, no fields, or an invalid identifier combination.

{
  "detail": {
    "status": "NO_PERSONS_PROVIDED",
    "message": "At least one person identifier must be provided"
  }
}

{
  "detail": {
    "status": "NO_FIELDS_PROVIDED",
    "message": "Provide at least one field name in 'fields', set 'include_personas' to true, set 'include_contact_data' to true, set 'enrich_company' to true or a list of company field names, or provide 'allow_signals'"
  }
}

401 — Invalid or missing API key

{ "detail": "Invalid API key" }

422 — Schema validation error

Returned when the JSON body fails Pydantic validation — for example, a PersonIdentifier with neither linkedin_url, nor work_email, nor a valid name + company combination; or an allow_signals.type value outside the SignalType enum; or an enrich_company value that is an empty list.

The response body conforms to HTTPValidationError.

{
  "detail": [
    {
      "loc": ["body", "persons", 0],
      "msg": "Value error, Provide linkedin_url, work_email, or a name (full_name OR first_name + last_name) together with a company identifier (company_domain or company_name)",
      "type": "value_error"
    }
  ]
}

429 — Rate limit exceeded

{ "detail": "Rate limit exceeded" }

500 — Internal enrichment failure

{
  "detail": {
    "status": "ENRICHMENT_FAILED",
    "message": "An error occurred while processing the request"
  }
}