Entity Resolve
Resolve a polymorphic identifier to ranked entity candidates.
The entity resolve endpoint lets you look up entities by any combination of identifiers - phone number, email, canonical ID (MRN), external system ID, or entity UUID. It returns ranked candidates with confidence scores and match provenance, so callers know which identifiers actually matched each row.
This powers inbound caller identification, webhook entity matching, and any workflow where you know one or more identifiers and need to find the corresponding entity.
Endpoint
POST
/v1/{workspace_id}/entities/resolve
Resolve entity by identifier
Request Body
entity_type
string
Yes
Entity type filter (e.g. person). Scopes the lookup to the correct partition.
phone
string
No
E.164 phone number. Format-tolerant: 10-digit, 11-digit with country code, and E.164 with plus prefix are all accepted.
email
string
No
Email address. Matched case-insensitively.
canonical_id
string
No
Canonical or MRN identifier.
external_id
object
No
External system identifier reference. See below.
entity_id
string (UUID)
No
Direct entity UUID lookup.
limit
integer
No
Maximum candidates to return. Range: 1-50, default: 25.
At least one identifier (phone, email, canonical_id, external_id, or entity_id) must be provided. Requests with no identifiers return HTTP 400.
External ID Object
system
string
Yes
External system label (lowercase, e.g. epic, hubspot, charm).
value
string
Yes
System-issued identifier value.
The system field is informational for scoring. The lookup matches the value against all keys in the entity's external identifiers, regardless of key naming conventions used by different adapters.
Response
matches
array
Ranked list of candidate matches.
total
integer
Number of candidates returned.
Match Object
entity_id
string (UUID)
Matched entity ID.
entity_type
string
Entity type.
confidence
float
Match confidence (0-1).
matched_on
string[]
Identifier kinds that actually matched this row. Possible values: entity_id, phone, email, canonical_id, external_id.
summary
object
Compact identity card.
Summary Object
display_name
string or null
Display name.
name
string or null
Full name.
phone
string or null
Phone number.
email
string or null
Email address.
birth_date
string or null
Date of birth.
mrn
string or null
Medical record number.
canonical_id
string or null
Canonical identifier.
external_ids
object
External system identifiers.
last_event_at
string (datetime) or null
Last event timestamp.
event_count
integer
Total event count.
tags
string[]
Entity tags.
Ranking
Candidates are ranked by confidence (highest first), with ties broken by the number of identifiers that matched. A row matching both phone and email outranks a row matching only phone.
Direct UUID lookup (entity_id) returns confidence 1.0. Phone, canonical ID, and external ID matches use the same confidence tier as the platform's entity merge resolver. Email matches use a slightly lower confidence tier.
Example
Request:
Response:
Error Responses
400
No identifier provided or invalid input.
401
Missing or invalid API key.
422
Validation error (e.g. limit out of range, malformed email).
Last updated
Was this helpful?