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

# Upsert Contact

> Create a new contact or update an existing one (upsert by email or phone).

```
upsert_contact
```

## Description

Creates a new contact or updates an existing one in the Birdeye account. If a contact with the provided email or phone already exists, it is updated. To explicitly update an existing contact, provide the `id` or `externalId`.

## Parameters

### Required

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `businessNumber` | integer | Yes | — | Enterprise business ID (from `get_business_info → businessId`) |
| `email` | string | Conditional | — | Contact email address — required if `phone` is not provided |
| `phone` | string | Conditional | — | Contact phone number — required if `email` is not provided |

### Optional

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `firstName` | string | No | — | Contact's first name |
| `lastName` | string | No | — | Contact's last name |
| `countryCode` | string | No | — | Country code (e.g. `"US"`) |
| `id` | string | No | — | Existing Birdeye contact ID — provide to update a specific contact |
| `externalId` | string | No | — | Your CRM/external system ID — provide to update a contact matched by external ID |
| `businessIds` | list\[integer] | No | — | Child location IDs to associate the contact with. Required when creating a new contact — ask the user to provide these directly |
| `smsOptin` | boolean | No | — | Whether the contact has opted in to SMS |
| `blocked` | boolean | No | — | Whether the contact is blocked |
| `tags` | list\[string] | No | — | Tags to associate with the contact |
| `emailPreferences` | object | No | — | `{ marketingOptin, feedbackOptin, serviceOptin }` |
| `smsPreferences` | object | No | — | `{ marketingOptin, feedbackOptin, serviceOptin }` |

## Example Usage

```
Create a new contact for John Doe (john.doe@example.com, 555-0100) and associate them with location 78901.
```

```
Update the SMS opt-in status to true for existing contact ID c_abc123.
```

## Notes

* To **create** a contact: omit `id` and `externalId`, and provide `businessIds` along with `email` or `phone`.
* To **update** a contact: provide `id` (Birdeye contact ID) or `externalId` (your CRM ID).
* `businessIds` takes child location IDs — do not call `get_child_locations` automatically; ask the user to provide them directly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.