Schemas

All request and response models used by the Data Access API. Each endpoint page links back here for identifier and response shapes.

CompanyIdentifier

Uniquely identifies a company for enrichment. Provide at least one of website, linkedin_url, or linkedin_id. When multiple identifiers are supplied the system uses them together for higher-confidence matching.

Field	Type	Required	Description
website	string	One-of	The company’s primary website domain or full URL (e.g. "crowdstrike.com" or "https://www.crowdstrike.com"). The domain is normalized internally, so both formats are accepted.
linkedin_url	string	One-of	The company’s LinkedIn page URL (e.g. "linkedin.com/company/crowdstrike"). The https://www. prefix is optional and will be normalized.
linkedin_id	string	One-of	The numeric LinkedIn company ID (e.g. "2135371"). Use this when the LinkedIn URL is not available but the ID is known.
external_id	string	No	A caller-supplied identifier (e.g. row number, UUID, external system ID). Not used for matching — echoed back in the response’s identifier dict so you can correlate results with your source records.

{
  "website": "crowdstrike.com",
  "linkedin_url": "linkedin.com/company/crowdstrike",
  "external_id": "sheet_row_42"
}

PersonIdentifier

Uniquely identifies a person for enrichment. The API supports several resolution strategies, listed from fastest to most flexible:

Strategy	Required fields	Notes
LinkedIn URL	linkedin_url	Direct lookup — fastest, no identity resolution needed.
Work email	work_email	Resolved via the Matchbox identity graph.
Full name + domain	full_name + company_domain	Resolved via Matchbox.
Full name + company name	full_name + company_name	Resolved via Matchbox when only the company name is known.
First/last + domain	first_name + last_name + company_domain	Resolved via Matchbox; names are joined internally.
First/last + company name	first_name + last_name + company_name	Resolved via Matchbox when only the company name is known.
All combined	work_email + name fields + company fields	Highest-confidence Matchbox resolution.

You must supply at least one valid combination above.

Field	Type	Description
linkedin_url	string	The person’s LinkedIn profile URL (e.g. "linkedin.com/in/scott-goldman-1736a0"). Direct lookup — no identity resolution. The https://www. prefix is optional.
work_email	string	Professional / work email address (e.g. "scott.goldman@bankofamerica.com"). Resolved via Matchbox. Can be combined with name and company fields for higher accuracy.
full_name	string	Full name as it appears 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.
last_name	string	Family name (e.g. "Goldman"). Must be provided together with first_name and at least one company identifier.
company_domain	string	The website domain of the person’s current employer (e.g. "bankofamerica.com"). Do not include https:// or www. — just the bare domain.
company_name	string	The name of the person’s current employer (e.g. "Bank of America"). Can be provided 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.

{
  "linkedin_url": "linkedin.com/in/scott-goldman-1736a0",
  "external_id": "sheet_row_42"
}

AllowSignals

Controls optional signals retrieval from the signals database. All filter fields are optional — when omitted, no filtering is applied for that dimension. Pass {} to retrieve all signals without filters.

Field	Type	Description
start_time	string (ISO YYYY-MM-DD)	Include signals from this calendar date onward.
end_time	string (ISO YYYY-MM-DD)	Include signals through this calendar date inclusive. Omit this field (and start_time) to return all dates.
type	SignalType	Filter by signal type. When omitted or set to ALL, all signal types are returned.

{
  "start_time": "2024-09-01",
  "end_time": "2024-12-31",
  "type": "High Intent"
}

SignalType

Enum of signal-type values accepted by allow_signals.type (on enrich endpoints) and the type field on POST /v1/signals/get-signals.

Both snake_case and Title Case values exist in the enum because the signals database stores some types under one casing and some under the other. Use the value exactly as listed below — they are case-sensitive.

Pass ALL to bypass type filtering entirely (equivalent to omitting the field).

ALL
new_hire
Key Changes
Account Visitor
Prospect Visitor
Event Attendee
Member in a community of interest
Linkedin Job Post
tr
contact_website_visitor
Hiring Growth
Company Change
Promotion
Join Community
hiring_manager
role_change
account_website_visitor
Topic Engagement
Article
High Intent
Role Change
Change in position
Event Appearance
New Hire
change_company
Job Posting

SignalRecord

A single signal entry returned from the signals table. All fields are optional and may be null depending on the source row.

Field	Type	Description
date	string	Calendar date the signal was recorded.
signal_type	string	Signal type label.
message_text	string	Free-text description of the signal.
intent_holder_linkedin_url	string	LinkedIn URL of the person associated with the signal.
source_type	string	Source of the signal (e.g. article_engagement, event_attendance).

{
  "date": "2024-11-18",
  "signal_type": "High Intent",
  "message_text": "Engaged with a technical deep-dive article.",
  "intent_holder_linkedin_url": "linkedin.com/in/scott-goldman-1736a0",
  "source_type": "article_engagement"
}

EnrichmentResult

A single enrichment result for one company or person. Each result maps back to exactly one input identifier.

Field	Type	Description
identifier	object	The original identifier fields echoed back from the request. For person lookups that required identity resolution, an additional resolved_linkedin_url key is included showing which LinkedIn profile was matched.
data	object	The enriched data fields. Contains exactly the fields you requested. Values are null when a field was requested but no data is available. For person results, may also include personas (array of role tags), seniority (one of seniority_executive, seniority_director, seniority_teamlead, seniority_ic), email, phone, and a nested company object depending on request options.
matched	boolean	Whether the system found a matching record. When false, data contains the requested field keys with null values. Only matched results are billed.

HTTPValidationError

The body returned with a 422 response when the JSON request fails Pydantic / FastAPI validation. The detail array contains one entry per offending field.

Field	Type	Description
detail	ValidationError[]	One entry per invalid input field.

{
  "detail": [
    {
      "loc": ["body", "companies", 0],
      "msg": "Value error, At least one identifier (website, linkedin_url, or linkedin_id) must be provided",
      "type": "value_error"
    }
  ]
}

ValidationError

A single entry inside a HTTPValidationError.detail array.

Field	Type	Description
loc	(string | integer)[]	JSON-pointer-style path to the offending field (e.g. ["body", "companies", 0]).
msg	string	Human-readable error message.
type	string	Pydantic error type (e.g. value_error, missing, string_type).