---
title: "Identify or upsert a contact by external identifier"
method: POST
path: "/contacts/identify"
tags: ["contacts"]
---

# Identify or upsert a contact by external identifier

`POST /contacts/identify`

## Request

- Base URL: `https://corebee.ai/api/v1`
- URL: `https://corebee.ai/api/v1/contacts/identify`
- Auth: HTTP bearer

Resolves a contact by email or user_id, creating or updating it. Traits (plan, seats, mrr_cents, customer_since, last_usage_at) are accepted FLAT at the top of the body; arbitrary traits go under custom_attributes.

## Request body

- ContactIdentify: At least one of email or user_id is required.
  - `email` string, email
  - `user_id` string
  - `name` string
  - `plan` string
  - `seats` integer
  - `mrr_cents` integer
  - `customer_since` string, date-time
  - `last_usage_at` string, date-time
  - `custom_attributes` object

## Response `200`

Resolved (existing contact updated)

- object
  - `data` Contact, required
    - `id` string, uuid
    - `org_id` string, uuid
    - `name` string, nullable
    - `email` string, nullable
    - `phone_number` string, nullable
    - `avatar_url` string, nullable
    - `custom_attributes` object
    - `created_at` string, date-time

## Other responses

- `201`: Created
- `400`: Validation error
- `401`: Invalid or missing credential

---

[API](https://skmtc.dev/corebee/apis/corebee-api.md) · [All operations](https://skmtc.dev/corebee/apis/corebee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/corebee/apis/corebee-api/revisions/a48ea543b4dc?raw)