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

# Create and manage contacts

> Create, update, search, list, and delete Heymarket contacts, including custom fields, tags, and channel-based lookup.

Contacts are the people your team messages. Use contact endpoints to keep customer identity, phone numbers, email addresses, tags, ownership, opt-out state, and custom fields in sync with your system.

## Choose v1 or v2 contacts

Use the contact surface that matches the identifiers you have.

| Use case                                                                            | Endpoint family            |
| ----------------------------------------------------------------------------------- | -------------------------- |
| Create or update a basic phone-based contact with an integer contact ID             | v1 contact endpoints       |
| Retrieve or update a contact by UUID, or manage phone/email channels on one contact | v2 contact endpoints       |
| Find a contact when you only know a phone number or email address                   | `POST /v2/contacts/search` |

The v1 endpoints use integer `id` values. The v2 endpoints use the contact UUID as `contactID`.

## Create a contact

Create a v1 contact with `POST /v1/contact`. A phone number is required and must use E.164 digits without the leading plus sign.

```bash theme={null}
curl -X POST https://api.heymarket.com/v1/contact \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "first": "Jordan",
    "last": "Rivera",
    "email": "jordan.rivera@example.com",
    "tags": [
      { "tag_id": 55 },
      { "tag_id": 56 }
    ]
  }'
```

The response includes the contact `id`, revision, and UUID.

```json theme={null}
{
  "id": 98765,
  "rev": 1,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## Update a contact

Use `PUT /v1/contact/{id}` to update an existing v1 contact. Include `phone` in the request body.

```bash theme={null}
curl -X PUT "https://api.heymarket.com/v1/contact/98765?overwrite=false" \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "first": "Jordan",
    "custom": {
      "123": "Premium",
      "456": "2026-06-01"
    }
  }'
```

The `overwrite` query parameter controls custom-field updates:

* `overwrite=false` merges the provided custom fields with existing values.
* `overwrite=true` replaces existing custom field values with the object you provide.

<Note>
  Contact names are overwritten during update regardless of the `overwrite` value.
</Note>

## Work with custom fields

Custom field keys are numeric field IDs, not field names. Get the IDs before writing custom values.

```bash theme={null}
curl -X POST https://api.heymarket.com/v1/contact-fields \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Example response:

```json theme={null}
[
  { "id": 123, "title": "Plan" },
  { "id": 456, "title": "Renewal Date" }
]
```

Then pass those IDs as string keys in the contact `custom` object.

## Search by phone or email

Use `POST /v2/contacts/search` when you have a channel value and need the matching contact.

```bash theme={null}
curl -X POST https://api.heymarket.com/v2/contacts/search \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_channels": [
      {
        "channel_type": "phone",
        "channel_ids": ["15105553344"]
      }
    ]
  }'
```

You can omit `channel_type` when Heymarket can infer it from the value format.

## Add a contact channel

Use `POST /v2/contact/{contactID}/channel` to add another phone number, email address, or supported channel to an existing v2 contact.

```bash theme={null}
curl -X POST https://api.heymarket.com/v2/contact/a1b2c3d4-e5f6-7890-abcd-ef1234567890/channel \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "email",
    "channel_id": "jordan.rivera@example.com"
  }'
```

## List and delete contacts

Use `POST /v1/contacts` to paginate contacts. Pass the previous page's last timestamp as `date` to retrieve the next page. For example, if the last contact on the current page has `updated: "2026-04-12T15:30:00Z"`, use that timestamp as the next `date` cursor.

```bash theme={null}
curl -X POST https://api.heymarket.com/v1/contacts \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-04-01T00:00:00Z"
  }'
```

Delete a contact with `DELETE /v1/contact/{id}`.

```bash theme={null}
curl -X DELETE https://api.heymarket.com/v1/contact/98765 \
  -H "Authorization: Bearer YOUR_SIGNED_JWT"
```

## Related pages

<CardGroup cols={2}>
  <Card title="Contacts" icon="address-book" href="/concepts/contacts">
    Understand contact identifiers, channels, tags, and status.
  </Card>

  <Card title="Contacts reference" icon="code" href="/api-reference/contacts/overview">
    Review contact endpoints and field-level details.
  </Card>

  <Card title="Search contacts reference" icon="search" href="/api-reference/contacts/search">
    Look up contacts by phone number, email address, or another channel value.
  </Card>

  <Card title="Contact channel reference" icon="code" href="/api-reference/contacts/channels">
    Add a channel to an existing v2 contact.
  </Card>
</CardGroup>