Contacts · Solel//dev docs

The core keeps everyone's contacts, so the Contacts app, Mail, phones and your app all see the same people. Your back end reaches them through the core's contacts API, acting for the person using the app.

Grants and books

contacts.read lets your app read; contacts.write lets it change anything.
Call with your token and the person in X-Solel-Person, as Acting for a person describes.
book is mine (the default), the person's own contacts, or household, the shared book. Owners, admins and adults can change the household's book; children can only see it, and guests can't. See The household address book.

Endpoints

Endpoint	What it does
`GET /api/contacts?book=&q=&group=&favourites=1`	Lists contacts by name, each with `id`, `book`, `name`, `relationship`, `organisation`, `picture`, `favourite`, `groups` and `emails`. `q` searches names, numbers, addresses, organisations and places, ignoring case and accents
`POST /api/contacts`	Adds a contact: `book` and the fields below, plus `favourite`
`GET /api/contacts/{id}`	One contact. The `ETag` header is its version
`PUT /api/contacts/{id}`	Replaces its fields. Send `If-Match` with the etag you read, and a change made elsewhere gets `412` instead of being overwritten
`DELETE /api/contacts/{id}`	Deletes it. `If-Match` works here too
`PUT /api/contacts/{id}/favourite`	`{"on": true}` or `false`. Seeing the contact is enough
`GET /api/contacts/{id}/photo`, `GET /api/contacts/{id}/vcard`	Its photo, or `404`; and it as a `.vcf` file
`GET /api/contacts/books`	The books the person can see, with counts and whether they can change each (`canChange`)
`GET /api/contacts/people`	People with accounts on the server
`GET /api/contacts/duplicates?book=`	Contacts that look like the same person, each set with `why`
`POST /api/contacts/merge`	`{"book", "ids"}` folds the others into the first
`POST /api/contacts/import`	`{"book", "format": "vcard" or "csv", "data", "name", "merge", "group", "dryRun"}`. Up to 20,000 contacts and 64 MB at a time
`GET /api/contacts/export?book=`	The whole book as one `.vcf`
`POST /api/contacts/groups/rename`	`{"book", "from", "to"}`. An empty `to` takes everyone out of the group

Fields

{
  "firstName": "Sam", "lastName": "Nguyen", "relationship": "Sister",
  "jobTitle": "Designer", "organisation": "Harbour Design",
  "phones": [{ "label": "Mobile", "value": "0412 555 018" }],
  "emails": [{ "label": "Home", "value": "sam.nguyen@example.com" }],
  "addresses": [{ "label": "Home", "street": "14 Wattle Street", "locality": "Fremantle", "region": "WA", "postcode": "6160", "country": "" }],
  "websites": [],
  "birthday": "1993-03-14", "anniversary": "",
  "notes": "Allergic to peanuts.",
  "groups": ["Family"],
  "picture": "photo"
}

Labels are Mobile, Home, Work or Other, or one of your own.
Dates are YYYY-MM-DD, or --MM-DD when the year isn't known.
Pictures. picture is "" for initials, "photo" for the card's photo, or "preset:<name>" for one of Solel's pictures. Send photoData, a data: URL of a JPEG or PNG up to 512 KB, to set a new photo.
What comes back adds id, book, name, favourite, etag, createdAt, updatedAt and via, what last changed it, which is app:<name> for an app.

Contacts are kept as vCards, and a card a phone sent comes back exactly as it was apart from what's edited, so nothing your app doesn't know about is lost.

Opening a contact

To show someone a contact in the Contacts app, open it from your front end with solel.openApp('io.solel.contacts', '/contact/<id>'). See the reference.