Appearance
contacts
6 endpoints at a glance
| Method | Path | Summary |
|---|---|---|
GET | /contacts | List Contacts |
POST | /contacts | Create Contact |
GET | /contacts/{addressbook_id}/{uid} | Get Contact |
PUT | /contacts/{addressbook_id}/{uid} | Update Contact |
POST | /contacts/{addressbook_id}/{uid}/relocate | Relocate Contact |
POST | /contacts/{addressbook_id}/{uid}/sync | Sync Contact |
contacts
List Contacts
GET
/contacts
List the current user's contacts.
Omit addressbook_id for cross-book results (decision (4)). The
response always carries addressbook_id on each item so the SPA
can render per-row source badges.
Parameters
Header Parameters
authorization
Query Parameters
addressbook_id
q
page
Type
integer
Default
1limit
Type
integer
Default
50Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Create Contact
POST
/contacts
Create a contact in one of the user's addressbooks.
Builds a vCard 4.0, PUTs it to the chosen addressbook, re-fetches the
server's canonical copy, and mirrors it locally. Returns the new contact
doc (same shape as GET /contacts/{ab}/{uid}).
Parameters
Header Parameters
authorization
Request Body
application/json
JSON "name": { "first": "", "last": "", "additional": "", "prefix": "", "suffix": "", "display": "" }, "nickname": "string", "organization": "string", "title": "string", "emails": [ { "type": "string", "value": "" } ], "phones": [ { "type": "string", "value": "" } ], "urls": [ { "type": "string", "value": "" } ], "addresses": [ { "type": "string", "street": "", "city": "", "region": "", "code": "", "country": "", "extended": "", "box": "" } ], "birthday": "string", "note": "string", "categories": [ "string" ], "languages": [ "string" ], "addressbook_id": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Get Contact
Update Contact
PUT
/contacts/{addressbook_id}/{uid}
Update an existing contact (conditional on its etag).
Preserves the contact's existing UID and resource href. Returns the
refreshed contact doc. 404 if the contact is gone locally; 409 if it
changed on the server since we last synced (re-open and retry).
Parameters
Header Parameters
authorization
Path Parameters
addressbook_id*
Type
Requiredstring
uid*
Type
Requiredstring
Request Body
application/json
JSON "name": { "first": "", "last": "", "additional": "", "prefix": "", "suffix": "", "display": "" }, "nickname": "string", "organization": "string", "title": "string", "emails": [ { "type": "string", "value": "" } ], "phones": [ { "type": "string", "value": "" } ], "urls": [ { "type": "string", "value": "" } ], "addresses": [ { "type": "string", "street": "", "city": "", "region": "", "code": "", "country": "", "extended": "", "box": "" } ], "birthday": "string", "note": "string", "categories": [ "string" ], "languages": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Sync Contact
POST
/contacts/{addressbook_id}/{uid}/sync
Re-fetch this contact from the CardDAV server.
Returns {result, contact} — contact is the refreshed doc on
success, null if the server returned 404 and we deleted locally.
On a UID change, result.new_uid carries the new identity so the
SPA can redirect to its detail page.
Parameters
Header Parameters
authorization
Path Parameters
addressbook_id*
Type
Requiredstring
uid*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Relocate Contact
POST
/contacts/{addressbook_id}/{uid}/relocate
Move or copy a contact to another addressbook.
Both PUT the stored raw_vcard verbatim to the target (so PHOTO / X-* /
IMPP survive byte-for-byte), then re-GET and mirror locally. A copy mints
a fresh UID and leaves the source alone. A move keeps the UID, then
DELETEs the source and rewrites every cross-entity reference to the new
addressbook_id::uid — but only after the copy is confirmed on the
server, so a failed delete leaves a recoverable duplicate rather than
losing the card.
Parameters
Header Parameters
authorization
Path Parameters
addressbook_id*
Type
Requiredstring
uid*
Type
Requiredstring
Request Body
application/json
JSON "target_addressbook_id": "string", "mode": "move"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}