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

# Contacts

> Synchronize the people Peoplewisher should celebrate.

Contacts are the main resource in the Peoplewisher API.

The integration pattern is simple: **bring your people data to Peoplewisher and assign each person to the right Celebration Group.**

## Contact lifecycle

The API supports:

| Operation | Method   | Endpoint                    |
| --------- | -------- | --------------------------- |
| List      | `GET`    | `/v1/contacts`              |
| Create    | `POST`   | `/v1/contacts`              |
| Update    | `PATCH`  | `/v1/contacts/{contact_id}` |
| Delete    | `DELETE` | `/v1/contacts/{contact_id}` |

See the generated [API Reference](/api-reference/contacts-list) for complete parameters and schemas.

## Create a contact

A contact belongs to a Celebration Group through `group_id`.

```json theme={null}
{
  "first_name": "Ada",
  "last_name": "Okafor",
  "email": "ada@example.com",
  "phone": "+2348012345678",
  "birthday": "1994-10-12",
  "timezone": "Africa/Lagos",
  "group_id": 24
}
```

The public API accepts the birthday as a date. Peoplewisher stores the month, day, and year needed by its existing celebration engine.

## Required data

`first_name` and `group_id` are required.

For a birthday workflow, provide the person's birthday. Email, phone, WhatsApp phone, timezone, and other profile fields can be supplied when available.

## Update a contact

Use `PATCH` when a person's details change.

```bash theme={null}
curl -X PATCH https://api.peoplewisher.com/v1/contacts/4812 \
  -H "Authorization: Bearer $PEOPLEWISHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada.okafor@example.com",
    "birthday": "1994-10-13",
    "group_id": 24
  }'
```

If the birthday changes, Peoplewisher updates the birthday information used by its workflow engine.

## Delete a contact

```bash theme={null}
curl -X DELETE https://api.peoplewisher.com/v1/contacts/4812 \
  -H "Authorization: Bearer $PEOPLEWISHER_API_KEY"
```

The API deletes the contact belonging to the authenticated Peoplewisher account.

## Duplicate protection

Peoplewisher checks for an existing contact with the same phone number or email within the same group when creating a contact.

If a duplicate is found, the request is rejected rather than silently creating another record.

## Custom fields

Peoplewisher supports custom contact fields. They can be supplied through the `custom_fields` object where your account has the corresponding custom-field configuration.

The definition of those fields is managed in PeopleWisher.