# Sync your contacts and calendars

Keep your contacts in the apps you use every day, with CardDAV and CalDAV.

## Overview

Each Monica vault is an address book on your device. Contact changes sync in both directions. You can also subscribe to recurring dates and reminder deadlines; those are read-only.

**Deleting synced contacts.** Deleting a contact in a synced address book also deletes it in Monica and on your other synced devices. To stop syncing, disconnect the account instead of deleting its contacts.

## Before you connect

1. Open **Settings → Security and access → API keys** in Monica and choose **Create key**.
2. Name the key after your device, such as **My iPhone**. Under **What will use this key**, choose **Personal script**. This is the current label for a non-assistant connection; it does not change the key’s permissions.
3. Leave **Let this key read the values of fields marked sensitive** off unless this device needs them. When enabled, supported sensitive contact fields can also be changed by the device. Other apps with access to your device’s contacts may be able to read the downloaded information.
4. Create the key and copy it before leaving the screen: Monica shows it only once. Use a separate key for each device so you can disconnect one without affecting the others.

[Open Security settings](https://my.monicahq.com/settings/account/security#api-keys)

**Access to your vaults.** An API key can access every vault in your account. Selecting fewer address books in your app only changes what that app syncs; it does not restrict the key’s access. The key can also be used with the API.

## Connect your app

Menu names vary by app version. Contacts use CardDAV; calendars and reminder tasks use CalDAV.

Server address: `https://my.monicahq.com/dav`
Username: your Monica email address
Password: your API key, not your account password

### iPhone / iPad

1. In **Settings**, open **Apps → Contacts → Contact Accounts → Add Account**. On older versions, Contacts is directly under Settings.
2. Choose **Other → Add CardDAV Account**. Enter the server address, your Monica email and your API key from the connection details above. Give the account a recognisable description, such as Monica.
3. Save the account, open **Contacts → Lists**, and select your vault’s address book.

**Calendars and reminders.** In Settings, open **Apps → Calendar → Calendar Accounts → Add Account**, then **Other** (or **Add Other Account**) and **Add CalDAV Account**. Use the same connection details. Select the vault’s dates calendar in Calendar. Reminder tasks require an app that supports CalDAV task lists.

[Apple account setup](https://support.apple.com/guide/iphone/ipha0d932e96/ios)

### Mac

1. In **Contacts → Settings → Accounts**, click **+** and choose **Other Contacts Account**.
2. Choose **Manual** if asked for an account type. Fill in the server address, your Monica email and your API key, then sign in.
3. Select the vault’s address book in Contacts. Check the account’s fetch settings to choose how often it updates.

**Calendars and reminders.** In **Calendar → Add Account**, choose **Other CalDAV Account**, then **Manual**. Enter the same connection details and select the dates calendars you want. A separate app with CalDAV task support may be needed for reminder tasks.

[Apple Contacts setup](https://support.apple.com/guide/contacts/adbk27096/mac)
[Apple Calendar setup](https://support.apple.com/guide/calendar/icl4308d6701/mac)

### Android / DAVx5

1. Open **DAVx5**, add an account, and choose login with a **URL and user name**.
2. Use the server address as the base URL, your Monica email as the username, and your API key as the password.
3. Finish creating the account, grant the permissions needed for contacts and calendar sync, then enable the vault address books you want in DAVx5. Start a sync and select those address books in your contacts app.

**Calendars and reminders.** In the same DAVx5 account, enable the vault’s dates calendar and, if wanted, its reminders task list. DAVx5 syncs the data to your apps; showing reminder tasks also requires a compatible task app.

[DAVx5 setup and sync](https://manual.davx5.com/introduction.html)

### Thunderbird

1. Open **Address Book**. From the **New Address Book** menu, choose **Add CardDAV Address Book**.
2. Enter your Monica email as the username and the server address as the location. Continue and enter your API key when asked for a password.
3. Select the vault address books you want and finish setup.

**Calendars and reminders.** Choose **New Calendar → On the Network** in Calendar. Enter your Monica email and the server address, use the API key when prompted, and select the discovered calendars. Look in **Tasks** for reminder lists that you enabled.

[Thunderbird CardDAV setup](https://support.mozilla.org/en-US/questions/1392802)
[Thunderbird calendar setup](https://support.mozilla.org/en-US/kb/creating-new-calendars)

### Evolution / GNOME

1. In **Evolution**, choose **File → New → Address Book**, then select **CardDAV**.
2. Enter the server address as the URL and your Monica email as the user. Choose **Find Address Books** and enter your API key when prompted.
3. Choose a vault’s address book and save it. It is also available in GNOME Contacts. Repeat for another vault if needed.

**Calendars and reminders.** In Evolution, choose **File → New → Calendar**, select **CalDAV**, and use the same URL and credentials with **Find Calendars**. For discovery of address books, calendars and task lists together, use **File → New → Collection account** and supply the server under its advanced options.

[Evolution contacts](https://gnome.pages.gitlab.gnome.org/evolution/help/contacts-carddav.html)
[Evolution calendars](https://gnome.pages.gitlab.gnome.org/evolution/help/calendar-caldav.html)
[Evolution collection accounts](https://help.gnome.org/evolution/intro-account-types.html)

### KDE / Kontact

1. In Kontact’s **Contacts** view (KAddressBook), choose **File → New → Add Address Book** and select **DAV groupware resource**.
2. Enter your Monica email and API key. Use manual configuration for a server that is not in the provider list, choose CardDAV, and supply the server address.
3. Discover the available address books, select the vaults you want, and finish the resource setup.

**Calendars and reminders.** Configure CalDAV in the DAV groupware resource using the same server address and credentials. Select the dates and reminders collections you want; calendars and to-dos are shown in Kontact’s calendar component.

[KAddressBook setup](https://docs.kde.org/stable_kf6/en/kaddressbook/kaddressbook/getting-started.html)

## Check your connection

1. Open your contacts app and select the address book named after your Monica vault. Find a contact you already know is in that vault.
2. Change that contact’s nickname in Monica, then refresh or sync the app. Check that the new nickname appears.
3. Change the nickname back in the app, sync again, and refresh the contact in Monica. This checks both directions without creating a duplicate.

Your app controls when it syncs. Changes may need a manual refresh or the next scheduled sync; they are not guaranteed to appear immediately.

## What syncs

Only contacts that are neither archived nor names-only appear in an address book. Each vault has its own address book; create, rename or delete vaults in Monica.

| Information | What reaches your address book |
| --- | --- |
| Names and nickname | First, middle and last names, prefix, suffix and nickname. Maiden name and name-order preferences stay in Monica. |
| Contact photo | The contact’s uploaded photo. Initials are not exported as a picture. |
| Email, phone, website and postal address | Values from matching fields in the contact’s template, including repeated values. Labels are sent where supported by the app. |
| Birthdays and other recurring dates | Dates from recurring-date fields with a known month. A date with an unknown year is sent without inventing a birth year; how it appears depends on the app. |
| Other information in Monica | Notes, documents, relationships, activity history and other field types are not exported to the address book. |

Without the sensitive-fields option, Monica does not add sensitive field values to the card or accept changes to those fields. This is not a way to erase information a device already has: properties previously saved on the synced card can still be returned.

## Editing and deleting

**Create a contact.** Save it into the address book for the intended vault. Monica creates a contact using that vault’s default template. A contact needs a name. Saving into a local, iCloud or Google address book does not add it to Monica.

**Edit contact details.** Supported details are written into the contact’s template fields. Repeated fields can hold several values. If the template only has room for one phone number, the first goes into that field; extra numbers remain on the synced card and can reach other devices without appearing as fields in Monica.

**Keep extra device information.** Monica keeps additional card properties that do not match its fields. The last card saved by a device replaces the previous one. If an app removes a property it does not understand, that property can disappear from other devices too.

**Remove information.** Removing a supported value in your app removes it from the matching Monica field, provided the key can change that field. The contact representing you cannot be deleted from a device. Device changes are recorded in Settings → Logs with the key’s name.

**Resolve a conflict.** When an app sends the version it last read, Monica rejects a save if that version has since changed. Refresh the contact, review the latest details and reapply your edit. Conflict handling depends on the app.

**Moving between vaults.** Moving a contact between two vault address books creates a new contact in the destination and deletes the source contact. Only the card’s information transfers. Reminders, history and other Monica information stay with the deleted source record.

## Calendars and reminders

**Dates calendar.** Each vault offers a calendar named “Vault name · dates”. Recurring dates appear as yearly, all-day events named after the contact and the field. When the year is unknown, the recurrence starts in the current year. Dates with an unknown month and fields marked sensitive are excluded, even when the key allows sensitive contact fields.

**Reminders task list.** “Vault name · reminders” contains the deadlines awaiting an answer within Monica’s reminder window. The due time is displayed in your device’s time zone. Answered or cancelled deadlines leave the list. These are tasks, not calendar events: your app must support CalDAV tasks (VTODO) to show them.

**Make changes in Monica.** Both subscriptions are read-only. Change a recurring date on the contact in Monica. Answer or manage a reminder in Monica; you cannot complete, reschedule or delete it from the synced task list.

## Troubleshooting

**My password is rejected.** Use your Monica email address as the username and the complete API key as the password, with no extra spaces. Your account password will not work. If the key was revoked or you no longer have it, create a new one.

**The app cannot find my account.** Copy the full server address from Connect your app, including /dav. Use manual setup or login with a URL when offered. Make sure your device can reach your Monica instance and trusts its HTTPS certificate. Opening the address in a browser is not a sync test.

**A contact or field is missing.** Check that the vault’s address book is enabled in the app. Archived and names-only contacts are excluded. Check the supported fields above and whether the key allows sensitive fields. Information saved to another account on the device will not appear in Monica.

**Dates appear, but reminders do not.** Enable the vault’s reminders list as well as its dates calendar. Your app must support CalDAV tasks (VTODO); support for calendar events alone is not enough.

**A change is refused.** Calendars and reminder lists are read-only. A contact needs a name, an organisation, a nickname, an email address or a phone number, and the contact representing you cannot be deleted or moved. For a version conflict, refresh the contact before editing again.

**Sync is delayed or reports too many requests.** Refresh the app and check its sync schedule. Monica allows 60 requests per minute per user, shared with API requests. Separate device keys do not increase this limit. If the app hits it, let it retry after the limit resets.

## Disconnect a device

1. In Monica, open **Settings → Security and access → API keys** and revoke the key named after the device. It stops working on the next request. If you reused the key, every app using it loses access.
2. Remove the Monica account from the device’s account or sync settings. Do not delete its contacts one by one while sync is still active.
3. Check the device for downloaded or exported copies. Revoking a key stops future access; it does not remotely erase data already copied to the device.
