get_person

Description: Retrieve detailed person profiles by person IDs with optional export

Tool Identifier: get_person

Input Parameters

Parameter	Type	Required	Default	Constraints	Description
person_ids	array	Yes	-	Max 1000 IDs, each string or integer	Array of person IDs to retrieve
domains	array	Yes	-	Must be subset of: `["address", "affinity", "content", "demographic", "email", "employment", "financial", "household", "id", "intent", "interest", "lifestyle", "maid", "name", "phone", "political", "purchase"]` (17 available domains)	Domains to include in the response
location	object	No	-	Lat/lng/radius/unit	Geospatial filter
format	string	No	"none"	"none", "csv", "json", "jsonl"	Export format - generates presigned S3 URL valid for 1 hour
workflow_id	string	No	-	Valid UUID	Workflow session identifier for correlation

Parameter Details:

person_ids:

Array of person IDs (strings or integers)
Maximum of 1000 person IDs per request
IDs should be the internal person_id values from the database
Empty array returns empty result
Example:
```
["123456789", 987654321, "555000111"]
```

domains:

Controls which data domains (tables) are included in the response
Required parameter - must specify at least one domain
Available domains (each maps to a person_<domain> table):
- 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
Example:
```
["name", "email", "demographic"]
```

location:

Optional geospatial filter
Only returns persons within the specified radius of the coordinates
Combined with person_ids filter (returns intersection)

Example:

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

format:

When set to csv, json, or jsonl, generates S3 presigned download URL
URL expires in 1 hour
Returns export metadata in response

workflow_id:

Optional UUID for tracking related tool calls in a session
If not provided, a new workflow_id is generated
Used for feedback correlation

Request Schema:

{
  person_ids: z.array(z.union([z.string(), z.number().int()])).max(200000),
  domains: z.array(z.enum(availableDomains)),
  location?: {
    latitude: number,   // -90 to 90
    longitude: number,  // -180 to 180
    radius: number,
    unit: "km" | "miles"
  },
  format?: "none" | "csv" | "json" | "jsonl",
  workflow_id?: string
}

Output Format

Success Response:

{
  profiles: Array<{
    person_id: string;
    metadata?: {
      quality_score?: number;
      last_modified?: string;
      [key: string]: any;
    };
    domains: {
      // Contact domains - arrays of objects with metadata
      names?: Array<{
        first_name?: string;
        last_name?: string;
        full_name?: string;
        middle_name?: string;
        prefix?: string;
        suffix?: string;
      }>;
      addresses?: Array<{
        address_primary?: string;
        address_secondary?: string;
        city?: string;
        state?: string;
        zip?: string;
        zip4?: string;
      }>;
      phones?: Array<{
        phone_number: string;
        phone_type?: string;    // "cell", "landline", "voip"
        carrier?: string;
        do_not_call?: boolean;  // TCPA compliance flag
      }>;
      emails?: Array<{
        email_address: string;
        opted_in?: boolean;     // CAN-SPAM compliance flag
      }>;
      maids?: Array<{
        device_id: string;
        id_type?: string;       // "IDFA", "GAID", etc.
        opted_out?: boolean;    // Privacy compliance flag
      }>;
      // Enrichment domains - structured objects
      [key: string]: any;
    };
  }>,
  export?: {
    url: string;
    format: "csv" | "json" | "jsonl";
    rows: number;
    size_bytes: number;
    expires_at: string;
  },
  tool_trace_id: string,
  workflow_id: string
}

Response Fields:

Field	Type	Description
profiles	array	Array of person profiles
profiles[].person_id	string	Unique person identifier
profiles[].metadata	object	Quality scores, timestamps, etc.
profiles[].domains	object	Domain data (see Contact Metadata below)
export	object	Export metadata (only when format is csv/json/jsonl)
export.url	string	Presigned S3 download URL (expires in 1 hour)
export.format	string	Export format
export.rows	number	Number of rows in export
export.size_bytes	number	File size in bytes
export.expires_at	string	ISO 8601 expiration timestamp
tool_trace_id	string	OpenTelemetry trace ID for this tool execution
workflow_id	string	Workflow session identifier

Contact Metadata (v1.8.0)

All contact domains return rich metadata objects instead of simple string arrays. These metadata fields enable compliance filtering and targeting:

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 targeting
`email`	`emails`	`email_address`, `opted_in`	CAN-SPAM compliance
`phone`	`phones`	`phone_number`, `phone_type`, `carrier`, `do_not_call`	TCPA compliance, SMS targeting
`maid`	`maids`	`device_id`, `id_type`, `opted_out`	Privacy compliance

Example Response:

{
  "profiles": [
    {
      "person_id": "123456789",
      "domains": {
        "names": [
          {
            "first_name": "Jane",
            "last_name": "Smith",
            "full_name": "Jane Smith"
          }
        ],
        "phones": [
          {
            "phone_number": "+15551234567",
            "phone_type": "cell",
            "carrier": "Verizon",
            "do_not_call": false
          }
        ],
        "emails": [
          {
            "email_address": "jane.smith@example.com",
            "opted_in": true
          }
        ],
        "demographic": {
          "age_range": "35-44",
          "gender": "female"
        }
      }
    }
  ],
  "tool_trace_id": "a1b2c3d4e5f6",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Handling

Error Response Format:

{
  "content": [
    {
      "type": "text",
      "text": "Person profile retrieval failed: <error message>"
    }
  ],
  "isError": true
}

Common Errors:

Empty person_ids array (returns empty array, not an error)
More than 200000 person IDs provided: "Maximum 200000 person IDs allowed per request"
Invalid person_id format: "Invalid person ID format"
Service temporarily unavailable: "Request failed - please try again"
Request timeout: "Request took too long - try reducing batch size"

Performance Notes

Maximum 200000 person IDs per request (enforced)
Efficient for batch lookups when you already have person IDs
Returns only matching records (no entries for non-existent IDs)
Specify only the domains you need for faster responses

Usage Examples

Example 1: Basic person lookup

{
  "person_ids": ["person_123", "person_456"],
  "domains": ["name", "email"]
}

Example 2: Full profile with mobile ad IDs

{
  "person_ids": ["person_789"],
  "domains": ["name", "email", "phone", "maid", "demographic", "lifestyle", "affinity"]
}

Example 3: Location-filtered lookup

{
  "person_ids": ["p1", "p2", "p3", "p4", "p5"],
  "domains": ["name", "email", "address"],
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 10,
    "unit": "km"
  }
}

Example 4: Export to CSV

{
  "person_ids": ["p1", "p2", "p3"],
  "domains": ["email", "phone"],
  "format": "csv"
}