Entity Resolve

Resolve a polymorphic identifier to ranked entity candidates.

Entity resolve looks up entities by phone number, email, canonical identifier, external-system identifier, entity UUID, or a combination of identifiers. It powers inbound caller identification, webhook matching, and other workflows that need to turn an external identifier into a workspace entity.

Resolve an Entity

Resolve entity by identifier

post

Polymorphic identifier → ranked entity candidates. Accepts any subset of {phone, email, canonical_id, external_id, entity_id} plus a required entity_type. Served from the SDP serving surfaces: entity rows from world.entities_synced; canonical_id and external_id resolve through world.canonical_entity_map_synced point reads. Returns matches ranked by confidence + number of identifiers matched. Summary narrowing: external_ids is always {}, tags is always [], and canonical_id is the canonical-map value or the entity's MRN.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

Polymorphic identifier query.

Provide entity_type plus any subset of identifier fields. Each identifier is OR-ed in SQL; matches are ranked by confidence and by the number of identifiers that actually matched the row. Returns at most limit candidates (default 25, max 50).

For latency-sensitive callers (inbound voice, webhook handlers), pass exactly one identifier — the indexed lookup is sub-10ms. Multi-identifier queries are useful for confirming a row matches on more than one signal (phone + email + MRN).

entity_typestring · min: 1 · max: 64Required

Required entity type filter (e.g. 'person'). Narrows the scan to the right index.

Pattern: ^[a-z0-9_]+$

phonestring · min: 2 · max: 16 · nullableOptional

E.164 phone number.

emailstring · email · nullableOptional

Primary email (case-insensitive match).

canonical_idstring · min: 1 · max: 256 · nullableOptional

Canonical identifier as carried by the canonical entity map (e.g. 'charm:Patient:42'; a raw MRN resolves only when a producer minted it as the canonical_id).

entity_idstring · uuid · nullableOptional

Direct UUID lookup. Useful for confirming an entity exists / re-fetching summary.

limitinteger · min: 1 · max: 50Optional

Maximum candidates to return.

Default: 25

Responses

200

Successful Response

application/json

totalintegerRequired

Number of candidates returned.

400

No identifier provided or invalid input.

401

Missing or invalid API key.

422

Validation Error

application/json

post/v1/{workspace_id}/world/entities/resolve

POST /v1/{workspace_id}/world/entities/resolve HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "entity_type": "text",
  "phone": "text",
  "email": "[e-mail]",
  "canonical_id": "text",
  "external_id": {
    "system": "text",
    "value": "text"
  },
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "limit": 25
}

{
  "matches": [
    {
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_type": "text",
      "confidence": 1,
      "matched_on": [
        "entity_id"
      ],
      "summary": {
        "display_name": "text",
        "name": "text",
        "phone": "text",
        "email": "text",
        "birth_date": "text",
        "mrn": "text",
        "canonical_id": "text",
        "external_ids": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "last_event_at": "2026-01-01T00:00:00.000Z",
        "event_count": 0,
        "tags": [
          "text"
        ]
      }
    }
  ],
  "total": 1
}

At least one identifier is required. An external-system identifier is system-qualified: resolution checks canonical keys for supported resource types and the bare value used by producers that minted it as a canonical identifier. An external ID that was never minted into the canonical map is not resolvable through this operation.

Ranking

Candidates are ranked by identifier-match confidence and then by the number of identifiers that matched. A direct UUID match has confidence 1.0; at the same confidence, a row matching both phone and email ranks above one matching only phone. This ranking uses identifier-match weights, not the world-event source classes described in Confidence as Trust Architecture. It is neither a calibrated probability of identity nor a substitute for identity verification.

Example

{
  "entity_type": "person",
  "phone": "[phone]",
  "email": "[e-mail]",
  "limit": 5
}

Requests without an identifier return 400; malformed values return 422.