entity_enrich

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": ["entity_123", "entity_456"],
  "domains": ["name", "email"]
}

Input Parameters

Parameter	Type	Required	Default	Constraints	Description
entity_type	string	Yes	-	"person" or "business"	Type of entity to enrich
entity_ids	array	Conditional	-	Max 1000, string or integer	Entity IDs to enrich. Mutually exclusive with csv_resource_uri
csv_resource_uri	string	Conditional	-	workflow:// URI	CSV with entity IDs. Mutually exclusive with entity_ids
entity_id_column	string	No	"entity_id"	Column name	Column containing entity IDs (only with csv_resource_uri)
domains	array	Yes	-	See available domains	Domain fields to include in response
location	object	No	-	lat/lng/radius/unit	Geospatial filter
format	string	No	"none"	"none", "csv", "json", "jsonl"	Export format
workflow_id	string	No	-	Valid UUID	Workflow session identifier

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 1000 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

domains:

Controls which data domains are included in the response
Required parameter - must specify at least one domain
Available domains (17):
- address - Physical addresses
- affinity - Brand and category affinities
- content - Content consumption patterns
- demographic - Age, gender, education, ethnicity, etc.
- email - Email addresses
- employment - Job and career information
- financial - Financial status and credit
- household - Household composition
- id - Identity information
- intent - Intent categories and topics
- interest - Interests and hobbies
- lifestyle - Lifestyle choices
- maid - Mobile advertising IDs
- name - Person names
- phone - Phone numbers
- political - Political data
- purchase - Purchase history

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;
  domains: Array<"address" | "affinity" | "content" | "demographic" | "email" | "employment" | "financial" | "household" | "id" | "intent" | "interest" | "lifestyle" | "maid" | "name" | "phone" | "political" | "purchase">;
  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; }>;
      addresses?: Array<{ address_primary?: string; city?: string; state?: string; zip?: string; }>;
      phones?: Array<{ phone_number: string; phone_type?: string; do_not_call?: boolean; }>;
      emails?: Array<{ email_address: string; opted_in?: boolean; }>;
      maids?: Array<{ device_id: string; id_type?: string; opted_out?: boolean; }>;
      [key: string]: any;
    };
  }>,
  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:

Field	Type	Description
profiles	array	Array of entity profiles
profiles[].entity_id	string	Unique entity identifier
profiles[].metadata	object	Quality scores, timestamps
profiles[].domains	object	Domain data (see Contact Metadata)
export	object	Export metadata (when format is csv/json/jsonl)
export.resource_uri	string	Workflow resource URI for the exported file
tool_trace_id	string	OpenTelemetry trace ID
workflow_id	string	Workflow session identifier

Contact Metadata

All contact domains return rich metadata objects with compliance fields:

Input Domain	Output Key	Object Fields	Use Case
`name`	`names`	`first_name`, `last_name`, `full_name`, `middle_name`, `prefix`, `suffix`	Personalization
`address`	`addresses`	`address_primary`, `address_secondary`, `city`, `state`, `zip`, `zip4`	Direct mail
`email`	`emails`	`email_address`, `opted_in`	CAN-SPAM compliance
`phone`	`phones`	`phone_number`, `phone_type`, `carrier`, `do_not_call`	TCPA compliance
`maid`	`maids`	`device_id`, `id_type`, `opted_out`	Privacy compliance

Example Response:

{
  "profiles": [
    {
      "entity_id": "123456789",
      "domains": {
        "names": [
          {
            "first_name": "Jane",
            "last_name": "Smith",
            "full_name": "Jane Smith"
          }
        ],
        "phones": [
          {
            "phone_number": "+15551234567",
            "phone_type": "cell",
            "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"
Neither provided: "Either entity_ids or csv_resource_uri must be provided"
More than 1000 entity IDs: "Maximum 1000 entity IDs allowed"
Service temporarily unavailable: "Request failed - please try again"

Usage Examples

Example 1: Basic entity lookup

{
  "entity_type": "person",
  "entity_ids": ["entity_123", "entity_456"],
  "domains": ["name", "email"]
}

Example 2: Full profile enrichment

{
  "entity_type": "person",
  "entity_ids": ["entity_789"],
  "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": ["e1", "e2", "e3"],
  "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": ["e1", "e2", "e3"],
  "domains": ["email", "phone"],
  "format": "csv"
}