Skip to main content
Kai matches a write to a contact by identity. An identity is one handle that belongs to one person. A contact can hold many.

​
The four kinds

external_id, email and phone become identities on their own. You do not need the identities array for them. Use that array for a channel handle, or for a second email address.

​
Normalization

Kai stores an identity in one form, and matches on that form:
  • an email address becomes lowercase;
  • a phone number keeps its digits only, and loses a 00 prefix;
  • an external value and a channel value keep their case, because they belong to another system.
Three spellings of the same number are therefore one identity: This is why a WhatsApp conversation and a contact from your CRM meet on the same record.

​
Match order

Kai reads the identities in the request and finds the contacts that hold them:
  1. no contact holds any of them: Kai creates a contact, and gives it every identity in the request;
  2. one contact holds one or more of them: Kai updates that contact, and adds the identities that it does not hold yet;
  3. two contacts hold them: Kai refuses the write.

​
Conflicts

The third case returns 409 and names the identities:
Kai does not merge the two contacts. A merge cannot be undone, and a wrong merge puts the history of one customer in front of another. Correct the conflict in Kai, under Contacts, or write to each contact by its Kai id.

​
Send at least one identity

POST /contacts refuses a request that carries no identity. Without one, Kai has nothing to match on, and a job that runs twice would make a second copy of every person.