entity_find

Find entities that match trait criteria and/or a geographic location filter, returning a sample of results with optional export.

Quick Example

{
  "entity_type": "person",
  "expression": "1000000001 AND 1000000002"
}

Input Parameters

Parameter	Type	Required	Default	Constraints	Description
entity_type	string	Yes	-	"person" or "business"	Type of entity to search
expression	string	No	-	Boolean expression	Trait IDs/hashes with AND/OR/NOT operators
location	object	No	-	lat/lng/radius/unit	Geospatial filter
identifier_type	string	No	-	See types	Single identifier type to return. Mutually exclusive with identifier_types
identifier_types	array	No	-	See types	Multiple identifier types. Mutually exclusive with identifier_type
audience_limit	number	No	1,000,000	1 to 15,000,000	Maximum entities to return
offset	number	No	0	>= 0	Pagination offset. Requires workflow_id when > 0
format	string	No	"none"	"none", "csv", "json", "jsonl"	Export format
workflow_id	string	No	-	Valid UUID	Required when offset > 0 for deterministic ordering

Parameter Details:

expression:

Boolean expression using trait IDs (numeric) or trait hashes (alphanumeric)
Supports: AND, OR, NOT, parentheses for grouping
Mixing trait IDs and trait hashes is allowed
Can be omitted for location-only queries
Important: Always call trait_list or trait_search first to discover valid trait IDs

Expression syntax:

"123 AND 456"                    // Both traits
"(123 OR 456) AND NOT 789"      // Either of two traits, excluding one
"abc123 AND def456"              // Using trait hashes
"123 AND abc123"                 // Mixing IDs and hashes

location:

Uses H3 resolution 9 (~0.2km edge length) for approximate radius matching

Example:

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

identifier_types:

Available types: "phone", "email", "address", "name", "maid"
By default returns entity_id and email
Allows exporting multiple contact columns in a single request

Request Schema:

interface EntityFindParams {
  entity_type: "person" | "business";
  expression?: string;
  location?: {
    latitude: number;
    longitude: number;
    radius: number;
    unit: "km" | "miles";
  };
  identifier_type?: "phone" | "email" | "address" | "name" | "maid";
  identifier_types?: Array<"phone" | "email" | "address" | "name" | "maid">;
  audience_limit?: number;
  offset?: number;
  format?: "none" | "csv" | "json" | "jsonl";
  workflow_id?: string;
}

Output Format

Success Response:

{
  total: number,
  returned_count: number,
  sample: Array<{
    entity_id: string;
    email?: string;
    phone?: string;
    name?: string;
    address?: string;
    maid?: string;
  }>,
  export?: {
    url: string;
    format: string;
    rows: number;
    size_bytes: number;
    expires_at: string;
    resource_uri: string;
  },
  has_more: boolean,
  next_offset?: number,
  tool_trace_id: string,
  workflow_id: string
}

Response Fields:

Field	Type	Description
total	number	Total entities matching criteria
returned_count	number	Number of samples returned
sample	array	Sample records (default 10)
export	object	Export metadata (when format is csv/json/jsonl)
export.resource_uri	string	Workflow resource URI for the exported file
has_more	boolean	Whether more results exist beyond current page
next_offset	number	Offset for next page (when has_more is true)
tool_trace_id	string	OpenTelemetry trace ID
workflow_id	string	Workflow session identifier

Example Response:

{
  "total": 245000,
  "returned_count": 10,
  "sample": [
    {
      "entity_id": "123456",
      "email": "alice@example.com"
    },
    {
      "entity_id": "789012",
      "email": "bob@example.com"
    }
  ],
  "has_more": true,
  "next_offset": 10,
  "tool_trace_id": "a1b2c3d4e5f6",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Handling

Common Errors:

Invalid trait ID in expression: "Trait not found"
No expression or location provided: At least one required
Invalid expression syntax: "Failed to parse boolean expression"
offset > 0 without workflow_id: "workflow_id is REQUIRED when offset > 0"

Usage Examples

Example 1: Simple trait-based search

{
  "entity_type": "person",
  "expression": "1000000001 AND 1000000002"
}

Example 2: Complex boolean with trait hashes

{
  "entity_type": "person",
  "expression": "(abc123 OR def456) AND NOT ghi789"
}

Example 3: Location-only search

{
  "entity_type": "person",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "radius": 25,
    "unit": "miles"
  }
}

Example 4: Combined trait + location with export

{
  "entity_type": "person",
  "expression": "1000000001 AND 1000000002",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 50,
    "unit": "km"
  },
  "identifier_types": ["email", "phone", "name"],
  "format": "csv"
}

Example 5: Paginated results

{
  "entity_type": "person",
  "expression": "1000000001",
  "offset": 100,
  "audience_limit": 50,
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Quick Example

Input Parameters

Output Format

Error Handling

Usage Examples

On this page