Retrieve detailed entity profiles by supplying entity IDs and specifying which data domains to include in the response.

Quick Example

{
  "entity_type": "person",
  "entity_ids": ["123456", "789012"],
  "domains": ["name", "email"]
}

Input Parameters

Parameter Details:

entity_type:

• Required. Use "person" for individual profiles or "business" for company profiles.

entity_ids:

• Array of entity IDs (strings or integers)
• Maximum of 200000 entity IDs per request
• Mutually exclusive with csv_resource_uri

csv_resource_uri:

• Workflow resource URI pointing to a CSV file containing entity IDs
• Use entity_id_column to specify which column contains the IDs (default: "entity_id")
• Mutually exclusive with entity_ids
• The CSV is processed in pages of up to 200,000 rows per call. When more rows remain, the response includes a next_offset field — pass it back as offset on the next call. The field is omitted on the last page.

domains:

• Controls which data domains are included in the response
• Required parameter - must specify at least one domain
• Domains not applicable to the requested entity_type (e.g., a business-only domain on a person lookup) return no data for that domain rather than an error.
• Values must be an exact lowercase match from the allowed set; namespaced forms such as social:linkedin are rejected. Use the bare social domain to retrieve all social networks in one request — the network is included in the returned contact JSON.
• Unknown values return a validation error that enumerates the full allowed set.

Identifier / contact domains (applicable to both person and business, except as noted):

• name - Person or company names
• email - Email addresses (person only)
• phone - Phone numbers
• address - Physical addresses
• maid - Mobile advertising IDs (person only)
• website - Website / primary domain (business only)
• social - Social handles for every supported network (the network is included in the returned contact JSON)

Person trait domains (applicable to person):

• affinity - Brand and category affinities
• content - Content consumption patterns
• demographic - Age, gender, education, ethnicity, etc.
• employment - Job and career information
• financial - Financial status and credit
• household - Household composition
• intent - Intent categories and topics
• interest - Interests and hobbies
• lifestyle - Lifestyle choices
• political - Political data
• purchase - Purchase history

Business trait domains (applicable to business):

• about - Company overview and description
• appstore - Mobile app presence and metadata
• digital - Digital footprint signals
• funding - Funding rounds and investors
• hiring - Open roles and hiring signals
• industry - Industry classification
• techstack - Technologies in use

location:

• Optional geospatial filter using H3 with dynamic resolution selection (3-9 based on radius)
• Only returns entities within the specified radius
• Example:

  {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 5,
    "unit": "km"
  }

Request Schema:

interface EntityEnrichParams {
  entity_type: "person" | "business";
  entity_ids?: Array<string | number>;
  csv_resource_uri?: string;
  entity_id_column?: string;
  offset?: number;
  limit?: number;
  domains: string[];
  location?: {
    latitude: number;
    longitude: number;
    radius: number;
    unit: "km" | "miles";
  };
  format?: "none" | "csv" | "json" | "jsonl";
  workflow_id?: string;
}

Output Format

Success Response:

{
  profiles: Array<{
    entity_id: string;
    metadata?: {
      quality_score?: number;
      last_modified?: string;
    };
    domains: {
      names?: Array<{ first_name?: string; last_name?: string; full_name?: string; middle_name?: string; prefix?: string; suffix?: string; company_name?: string; }>;
      addresses?: Array<{ address?: string; city?: string; state?: string; zip5?: string; zip4?: string; }>;
      phones?: Array<{ phone?: string; phone_type?: string; mobile_carrier?: string; on_do_not_call?: boolean; is_work_phone?: boolean; }>;
      emails?: Array<{ email?: string; opted_in?: boolean; }>;
      maids?: Array<{ device_id: string; device_id_type?: string; opted_out?: boolean; }>;
      websites?: Array<{ website?: string; domain?: string; domain_tld?: string; quality_score?: string | number; }>;
      linkedin?: Array<{ linkedin_url?: string; linkedin_url_id?: string; quality_score?: string | number; }>;
      [key: string]: any;
    };
  }>,
  missing_entity_ids?: string[],
  export?: {
    url: string;
    format: string;
    rows: number;
    size_bytes?: number;
    expires_at: string;
    resource_uri: string;
  },
  tool_trace_id: string,
  workflow_id: string
}

Response Fields:

Use missing_entity_ids to distinguish a data-coverage gap from invalid inputs: an ID appearing here is well-formed and was accepted, but no rows were available for the requested view. With a location filter applied, IDs outside the radius are reported as missing alongside IDs absent from v3.entity — both are legitimately absent from the result.

Contact Metadata

All contact domains return rich metadata objects with compliance fields:

Example Response:

{
  "profiles": [
    {
      "entity_id": "123456789",
      "domains": {
        "names": [
          {
            "first_name": "Jane",
            "last_name": "Smith",
            "full_name": "Jane Smith"
          }
        ],
        "phones": [
          {
            "phone": "+15551234567",
            "phone_type": "cell",
            "on_do_not_call": false
          }
        ],
        "demographic": {
          "age_range": "35-44",
          "gender": "female"
        }
      }
    }
  ],
  "tool_trace_id": "a1b2c3d4e5f6",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Handling

Common Errors:

• Both entity_ids and csv_resource_uri provided: "entity_ids and csv_resource_uri are mutually exclusive. Provide one or the other."
• Neither provided: "Either entity_ids or csv_resource_uri must be provided."
• More than 200000 entity IDs: "Maximum 200000 entity IDs allowed"
• More than 10000 entity IDs with format='none': "format='none' supports at most 10000 entity IDs. Received N. Use format='csv', 'json', or 'jsonl' for larger requests."
• Unknown domain value: returns a validation error whose message enumerates every legal domain — the caller should correct the value in one step rather than retry.

Usage Examples

Example 1: Basic entity lookup

{
  "entity_type": "person",
  "entity_ids": ["123456", "789012"],
  "domains": ["name", "email"]
}

Example 2: Full profile enrichment

{
  "entity_type": "person",
  "entity_ids": ["456789"],
  "domains": ["name", "email", "phone", "demographic", "lifestyle", "affinity"]
}

Example 3: CSV resource input

{
  "entity_type": "person",
  "csv_resource_uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/entities.csv",
  "entity_id_column": "id",
  "domains": ["demographic", "interest"]
}

Example 4: Location-filtered lookup

{
  "entity_type": "person",
  "entity_ids": ["111111", "222222", "333333"],
  "domains": ["name", "email", "address"],
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 10,
    "unit": "km"
  }
}

Example 5: Export to CSV

{
  "entity_type": "person",
  "entity_ids": ["111111", "222222", "333333"],
  "domains": ["email", "phone"],
  "format": "csv"
}

Example 6: Paginating a large CSV

For CSVs with more than 200,000 rows, paginate using the next_offset cursor returned in the response: pass it back as offset on the next call until the field is omitted (last page). offset, limit, and next_offset only apply on the CSV path; they are ignored when inline entity_ids are used.

{
  "entity_type": "person",
  "csv_resource_uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/entities.csv",
  "entity_id_column": "id",
  "offset": 200000,
  "limit": 200000,
  "domains": ["name", "email"]
}

Example 7: Business enrichment with trait domains

{
  "entity_type": "business",
  "entity_ids": ["112233"],
  "domains": ["name", "website", "industry", "funding", "techstack"]
}