Contacts
List, search, write and photo-download contacts across Google, Microsoft 365 and CardDAV.
Guides: Contacts.
| Method | Path | Operation | Scope |
|---|---|---|---|
GET | /v1/accounts/{accountId}/contacts | List or search contacts, by name | read |
POST | /v1/accounts/{accountId}/contacts | Create a contact | write |
GET | /v1/accounts/{accountId}/contacts/{contactId} | Get a contact | read |
PATCH | /v1/accounts/{accountId}/contacts/{contactId} | Change a contact | write |
DELETE | /v1/accounts/{accountId}/contacts/{contactId} | Delete a contact | write |
GET | /v1/accounts/{accountId}/contacts/{contactId}/photo | Download a contact's photo | read |
GET | /v1/accounts/{accountId}/contact-folders | List contact folders | read |
Runs in your browser against api.workwae.com with the key you enter. Use a read-only key, limited to a test account if you can.
Reads the index. q matches part of any name, the organization or any email address, case-insensitively.
Required scope: read.
accountId*stringuuidq?string1 <= length <= 200folderId?stringuuidlimit?integer1 <= value <= 500100cursor?string1 <= length <= 512OK
application/json- response
items*array<>nextCursor*|nullcurl -X GET 'https://api.workwae.com/v1/accounts/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/contacts'{ "items": [ { "id": "c4e6a8b0-1d3f-4a5c-8e7b-9d1f3a5c7e9b", "folderId": "708b432e-9495-4168-82e1-0cf52a8ef66f", "displayName": "string", "givenName": "string", "middleName": "string", "familyName": "string", "nickname": "string", "emails": [ { "address": "ada@example.com", "type": "home" } ], "phones": [ { "number": "string", "type": "mobile" } ], "organization": "string", "jobTitle": "string", "department": "string", "birthday": "string", "notes": "string", "hasPhoto": true, "updatedAt": "2026-05-04T09:30:00.000Z" } ], "nextCursor": "eyJ0eG5pZCI6IjQyIiwiaWQiOjEwMDF9"}Runs against the live API with the key you enter: this change really happens. Use a key limited to a test account.
Written to the provider, then to the index, so it is listed at once.
Required scope: write.
accountId*stringuuidapplication/json- body
folderId?stringuuiddisplayName?string1 <= length <= 256givenName?string1 <= length <= 256middleName?string1 <= length <= 256familyName?string1 <= length <= 256nickname?string1 <= length <= 256emails?array<>items <= 20phones?array<>items <= 20organization?string1 <= length <= 256jobTitle?string1 <= length <= 256department?string1 <= length <= 256birthday?string^(\d{4}-|--)\d{2}-\d{2}$notes?stringlength <= 10000OK
application/json- response
id*stringuuidfolderId*|nulldisplayName*string|nullgivenName*string|nullmiddleName*string|nullfamilyName*string|nullnickname*string|nullemails*array<>phones*array<>organization*string|nulljobTitle*string|nulldepartment*string|nullbirthday*string|nullnotes*string|nullhasPhoto*boolean|nullupdatedAt*stringdate-timecurl -X POST 'https://api.workwae.com/v1/accounts/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/contacts' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "c4e6a8b0-1d3f-4a5c-8e7b-9d1f3a5c7e9b", "folderId": "708b432e-9495-4168-82e1-0cf52a8ef66f", "displayName": "string", "givenName": "string", "middleName": "string", "familyName": "string", "nickname": "string", "emails": [ { "address": "ada@example.com", "type": "home" } ], "phones": [ { "number": "string", "type": "mobile" } ], "organization": "string", "jobTitle": "string", "department": "string", "birthday": "string", "notes": "string", "hasPhoto": true, "updatedAt": "2026-05-04T09:30:00.000Z"}Runs in your browser against api.workwae.com with the key you enter. Use a read-only key, limited to a test account if you can.
Reads the index.
Required scope: read.
accountId*stringuuidcontactId*stringuuidOK
application/json- response
id*stringuuidfolderId*|nulldisplayName*string|nullgivenName*string|nullmiddleName*string|nullfamilyName*string|nullnickname*string|nullemails*array<>phones*array<>organization*string|nulljobTitle*string|nulldepartment*string|nullbirthday*string|nullnotes*string|nullhasPhoto*boolean|nullupdatedAt*stringdate-timecurl -X GET 'https://api.workwae.com/v1/accounts/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/contacts/6181f81d-cf41-4ce3-b932-5cbe6b7d01c5'{ "id": "c4e6a8b0-1d3f-4a5c-8e7b-9d1f3a5c7e9b", "folderId": "708b432e-9495-4168-82e1-0cf52a8ef66f", "displayName": "string", "givenName": "string", "middleName": "string", "familyName": "string", "nickname": "string", "emails": [ { "address": "ada@example.com", "type": "home" } ], "phones": [ { "number": "string", "type": "mobile" } ], "organization": "string", "jobTitle": "string", "department": "string", "birthday": "string", "notes": "string", "hasPhoto": true, "updatedAt": "2026-05-04T09:30:00.000Z"}Runs against the live API with the key you enter: this change really happens. Use a key limited to a test account.
Fields present change (null clears); emails and phones replace the whole list.
Required scope: write.
accountId*stringuuidcontactId*stringuuidapplication/json- body
displayName?|nullgivenName?|nullmiddleName?|nullfamilyName?|nullnickname?|nullemails?array<>items <= 20phones?array<>items <= 20organization?|nulljobTitle?|nulldepartment?|nullbirthday?|nullnotes?|nullOK
application/json- response
id*stringuuidfolderId*|nulldisplayName*string|nullgivenName*string|nullmiddleName*string|nullfamilyName*string|nullnickname*string|nullemails*array<>phones*array<>organization*string|nulljobTitle*string|nulldepartment*string|nullbirthday*string|nullnotes*string|nullhasPhoto*boolean|nullupdatedAt*stringdate-timecurl -X PATCH 'https://api.workwae.com/v1/accounts/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/contacts/6181f81d-cf41-4ce3-b932-5cbe6b7d01c5' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "c4e6a8b0-1d3f-4a5c-8e7b-9d1f3a5c7e9b", "folderId": "708b432e-9495-4168-82e1-0cf52a8ef66f", "displayName": "string", "givenName": "string", "middleName": "string", "familyName": "string", "nickname": "string", "emails": [ { "address": "ada@example.com", "type": "home" } ], "phones": [ { "number": "string", "type": "mobile" } ], "organization": "string", "jobTitle": "string", "department": "string", "birthday": "string", "notes": "string", "hasPhoto": true, "updatedAt": "2026-05-04T09:30:00.000Z"}Runs against the live API with the key you enter: this change really happens. Use a key limited to a test account.
Required scope: write.
accountId*stringuuidcontactId*stringuuidOK
application/json- response
curl -X DELETE 'https://api.workwae.com/v1/accounts/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/contacts/6181f81d-cf41-4ce3-b932-5cbe6b7d01c5'nullRuns in your browser against api.workwae.com with the key you enter. Use a read-only key, limited to a test account if you can.
Fetched from the provider on first request and cached until the photo changes.
Required scope: read.
accountId*stringuuidcontactId*stringuuidThe photo as the provider stores it (image/jpeg, image/png, ...)
response?stringimage/*curl -X GET 'https://api.workwae.com/v1/accounts/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/contacts/6181f81d-cf41-4ce3-b932-5cbe6b7d01c5/photo'"string"Runs in your browser against api.workwae.com with the key you enter. Use a read-only key, limited to a test account if you can.
Microsoft 365 contact folders, the default folder first; empty for Google accounts.
Required scope: read.
accountId*stringuuidOK
application/json- response
items*array<>curl -X GET 'https://api.workwae.com/v1/accounts/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/contact-folders'{ "items": [ { "id": "c4e6a8b0-1d3f-4a5c-8e7b-9d1f3a5c7e9b", "name": "string", "isDefault": true } ]}