Contacts
List, search, create and change an account's contacts on Google, Microsoft 365 and CardDAV, and read their photos.
Read and write an account's address book through one API, whichever provider holds it.
Contacts and sync
- Google (People API) and Microsoft 365 accounts sync contacts while the account's
contactsEnabledsetting is on. - IMAP accounts sync over CardDAV once their IMAP settings name a CardDAV server.
- Reads come from Workwae's index. Writes go to the provider first, then to the index, so a new contact is listed at once.
| Status | Reason | When |
|---|---|---|
| 409 | contacts_disabled | The account does not sync contacts. |
| 403 | plan_module_unavailable | The plan has no contacts module. |
List and search
q matches part of any name, the organization or any email address, ignoring case. Pages hold up to 500 contacts.
curl "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/contacts?q=lovelace" \
-H "Authorization: Bearer $WORKWAE_API_KEY"Microsoft 365 contacts live in folders: GET .../contact-folders lists them (the default folder first; always empty for Google), and folderId narrows the list to one.
Create, change and delete
A new contact needs at least a name, an organization, an email address or a phone number (contact_unidentifiable otherwise).
curl -X POST "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/contacts" \
-H "Authorization: Bearer $WORKWAE_API_KEY" \
-H "content-type: application/json" \
-d '{
"givenName": "Ada",
"familyName": "Lovelace",
"emails": [{ "address": "ada@example.com", "type": "work" }],
"phones": [{ "number": "+44 20 7946 0000", "type": "mobile" }],
"organization": "Analytical Engines Ltd",
"birthday": "1815-12-10"
}'PATCH .../contacts/{contactId} changes the fields present; null clears a field, and emails and phones replace the whole list. DELETE .../contacts/{contactId} deletes the contact at the provider.
curl -X PATCH "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/contacts/$CONTACT_ID" \
-H "Authorization: Bearer $WORKWAE_API_KEY" \
-H "content-type: application/json" \
-d '{ "jobTitle": "Mathematician", "phones": [] }'
curl -X DELETE "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/contacts/$CONTACT_ID" \
-H "Authorization: Bearer $WORKWAE_API_KEY"Providers store different things:
| Provider | What it stores |
|---|---|
No folders (folderId is refused). A birthday may omit the year: --12-10. | |
| Microsoft 365 | At most 3 email addresses, one mobile number, and no other phone type; email addresses carry no type. More is refused as provider_unsupported. |
| CardDAV | Whatever the server keeps; at most 20 emails and phones each, as everywhere. |
Photos
GET .../contacts/{contactId}/photo answers the photo as the provider stores it (image/jpeg, image/png, ...). It is fetched on first request and cached until it changes.
hasPhotosays whether there is one; it isnullon Microsoft 365, which does not say without fetching it.- A contact without a photo answers 404
photo_not_found.
curl "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/contacts/$CONTACT_ID/photo" \
-H "Authorization: Bearer $WORKWAE_API_KEY" -o photoContact events
contact.created,contact.updated(naming the changed fields,photofor a new picture) andcontact.deletedreport changes made anywhere: through the API, in Gmail or Outlook, or on the CardDAV server.contacts.initializedmarks the end of an account's first contacts sync; nothing from before it is announced contact by contact.
Payloads are in Calendar and contacts events.