CardDAV and CalDAV

Sync your contacts and calendars

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

View as Markdown

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.

On this page

Before you connect

Open Security settings
  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.

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

Every app uses the same connection details. Menu names vary by version. Contacts use CardDAV; calendars and reminder tasks use CalDAV.

Use your instance’s address, without /dav. The server address below updates automatically.

Server address
https://my.monicahq.com/dav
Username
Your Monica email address
Password
Your API key. Your account password will not work.

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.

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.

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.

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.

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.

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.

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 synced to your address book
InformationWhat 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.

Sensitive fields and existing copies

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

Moving between vaults does not transfer the history

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.

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.

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.

Manage your API keys