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

# Look Up Or Upsert Contacts

> Resolve contacts by email without exposing email addresses in URLs.

## Look up by email

`POST /contacts/lookup`

```json theme={null}
{ "email": "olivia@example.com" }
```

The response is `200 OK` with `data: null` when no active contact exists.

## Upsert by email

`POST /contacts/upsert`

```json theme={null}
{
  "email": "olivia@example.com",
  "fields": {
    "first_name": "Olivia",
    "plan": "pro"
  }
}
```

Upsert merges provided fields, validates declared audience properties, and returns
the contact with `created: true` or `created: false`. Email is normalized per
project and concurrent requests resolve to one active contact.