Look up parent-child relationships between entities, such as employment or household connections.
Quick Example
{
"entity_type": "person",
"entity_ids": ["person_123"]
}Input Parameters
| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| entity_type | string | Yes | - | "person" or "business" | Type of the parent entity |
| entity_ids | array | Conditional | - | 1-1000 string IDs | Parent entity IDs. 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) |
| relationship | string | No | - | Relationship type | Filter by relationship type (e.g., "employed_by", "household_member") |
| related_entity_type | string | No | - | "person" or "business" | Filter by type of related entities |
| limit | number | No | 1000 | 1-10000 | Maximum relations to return |
| offset | number | No | 0 | >= 0 | Pagination offset |
| workflow_id | string | No | - | Valid UUID | Workflow session identifier |
Request Schema:
interface EntityRelationsParams {
entity_type: "person" | "business";
entity_ids?: string[];
csv_resource_uri?: string;
entity_id_column?: string;
relationship?: string;
related_entity_type?: "person" | "business";
limit?: number;
offset?: number;
workflow_id?: string;
}Output Format
{
relations: Array<{
parent_entity_id: string;
related_entity_id: string;
related_entity_type: "person" | "business";
relationship: string;
}>,
total: number,
returned: number,
has_more: boolean,
next_offset?: number,
tool_trace_id: string,
workflow_id: string
}Response Fields:
| Field | Type | Description |
|---|---|---|
| relations | array | Array of entity relationships |
| relations[].parent_entity_id | string | The input (parent) entity ID |
| relations[].related_entity_id | string | The related (child) entity ID |
| relations[].related_entity_type | string | Type of the related entity |
| relations[].relationship | string | Relationship type |
| total | number | Total matching relations |
| returned | number | Number returned in this page |
| has_more | boolean | Whether more results exist |
| next_offset | number | Offset for next page |
| tool_trace_id | string | OpenTelemetry trace ID |
| workflow_id | string | Workflow session identifier |
Example Response:
{
"relations": [
{
"parent_entity_id": "person_123",
"related_entity_id": "business_456",
"related_entity_type": "business",
"relationship": "employed_by"
},
{
"parent_entity_id": "person_123",
"related_entity_id": "person_789",
"related_entity_type": "person",
"relationship": "household_member"
}
],
"total": 2,
"returned": 2,
"has_more": false,
"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"
- Service temporarily unavailable: "Request failed - please try again"
Usage Examples
Example 1: Find employer for a person
{
"entity_type": "person",
"entity_ids": ["person_123"],
"relationship": "employed_by",
"related_entity_type": "business"
}Example 2: Find household members
{
"entity_type": "person",
"entity_ids": ["person_123", "person_456"],
"relationship": "household_member"
}Example 3: All relationships for an entity
{
"entity_type": "person",
"entity_ids": ["person_123"]
}Example 4: CSV resource input with pagination
{
"entity_type": "person",
"csv_resource_uri": "workflow://550e8400-e29b-41d4-a716-446655440000/uploads/people.csv",
"entity_id_column": "person_id",
"limit": 500,
"offset": 0
}