---
title: "Contacts and groups"
description: "Store recipients as contacts and organise them into groups."
---

> Documentation Index
> Fetch the complete documentation index at: https://dev.messageport.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts and groups

Contacts hold a recipient's number and details. Groups collect contacts so you can message them together from the web interface. You don't need contacts to [send messages](/guides/sending-messages/) through the API, but keeping them in sync lets your team see names in conversations and reports.

## Contacts

| Task | Endpoint |
|---|---|
| List or search contacts | [List contacts](/api/contacts/list/) |
| Get a contact | [Get contact](/api/contacts/get/) |
| Create a contact | [Create contact](/api/contacts/create/) |
| Update a contact | [Update contact](/api/contacts/update/) |
| Delete a contact | [Delete contact](/api/contacts/delete/) |

A contact needs a `number`. A name and email are optional.

- **Add to a group on create.** Pass `group` with a group's title. The group is created if it doesn't exist.
- **Avoid duplicates.** Pass `update_if_exists: true` to update the contact with that number if one exists, instead of creating another.
- **Custom fields.** `metadata` stores custom fields on the contact. Custom fields need to be set up on your account first; ask your account manager.

[List contacts](/api/contacts/list/) supports `search`, `sort_by`, `sort_order` and `per_page` (10 to 200). See [Pagination](/concepts/pagination/).

### Global contacts

Accounts with shared, account-wide contacts can include them in results by passing `with_global=true` to [List contacts](/api/contacts/list/).

## Groups

Groups are read-only over the API. Create and manage them in [MessagePort](https://app.messageport.com.au), or create one implicitly by passing `group` when you create a contact.

| Task | Endpoint |
|---|---|
| List groups | [List groups](/api/groups/list/) |
| Get a group | [Get group](/api/groups/get/) |

Source: https://dev.messageport.com.au/guides/contacts-and-groups/index.mdx