Resolve Entity

POST/v1/core/entities/resolve

Resolves one or more identifiers into a canonical entity. If the entity does not exist, it will be created. If identifiers match multiple entities, they will be intelligently merged.

Request

{
  "identifiers": {
    "email": "alice@volt.io",
    "stripe_cus": "cus_A1B2C3"
  },
  "display_name": "Alice Smith", 
  "entity_type": "customer",
  "metadata": {}
}

Parameters

Name	Type	Required	Description
identifiers	map[string]string	Yes	Map of source to identifier values (e.g. {"email": "x@y.com"})
display_name	string	No	Optional human-readable name for UI
entity_type	string	No	E.g. user, customer, issue
metadata	object	No	Custom JSON payload

Response

Returns the canonical entity data.

{
  "entity_id": "ent_550e8400-e29b-41d4-a716-446655440000",
  "display_name": "Alice Smith",
  "entity_type": "customer",
  "behavioral_score": 0.0,
  "successful_interactions": 0,
  "total_interactions": 0,
  "identifiers": [
    {
      "id": "ident_123",
      "identifier_type": "email",
      "identifier_value": "alice@volt.io",
      "source": "email"
    }
  ]
}