People

Read People: search by name, email, phone or relation word, list a view (touched by default), one person by id with full details, view "stats" for counts, or from/to for birthdays and important dates in a period. Search rows are compact. A search that finds nobody returns didYouMean (up to 3 likely people); ask the user one question naming them instead of searching again.

Note: Search with query; read one person with id; view 'circle' for stated relationships and pins, 'stats' for counts; from/to for birthdays and important dates in a period (at most 93 days).

{
  "query": "Priya"
}

Add one person. Only displayName is required; add contact points, addresses, tags, dates and notes when known. Set relationshipToMe only if the user has said what this person is to them. Resolve with people_find first so nobody is added twice.

Note: Resolve first with people_find so the same person is not added twice.

{
  "record": {
    "displayName": "Priya Shah",
    "givenName": "Priya",
    "familyName": "Shah",
    "emails": [
      {
        "id": "email1",
        "label": "Personal",
        "value": "priya.shah@example.com"
      }
    ],
    "birthday": "03-12",
    "birthYear": 1994
  }
}

Change one person by record.id: sent fields change, others keep their values; organization and relationshipToMe merge one level deep, ARRAYS replace wholesale (read the person first and send each array complete). Pin with pinned, archive with archived, state a relationship with relationshipToMe.

Note: Omitted fields keep their values; organization and relationshipToMe merge one level deep; arrays replace wholesale, so send the full list when changing one.

{
  "record": {
    "id": "person_priya",
    "nickname": "Pri"
  }
}

Permanently delete one person, remove them from moments, and drop relationship references from other people. Only on an explicit request; archiving (people_change archived) keeps them. Resolve the id with people_find first.

Note: Archiving (people_change with archived true) keeps the person instead.