---
title: "Identify a contact"
method: POST
path: "/contacts/identify"
---

# Identify a contact

`POST /contacts/identify`

## Request

- Base URL: `https://insights.reforge.com/api/v1`
- URL: `https://insights.reforge.com/api/v1/contacts/identify`
- Auth: HTTP bearer

## Request body

- Contact
  - `id` string, required: External contact ID
  - `shouldUnflattenProperties` boolean, nullable: Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`
  - `properties` object, nullable: Properties prefixed with `$` are handled specially. Otherwise, additional key-value pairs will be metadata once ingested into the system
    - `$email` string, nullable
    - `$name` string, nullable
    - `$createdAt` string, date-time, nullable
    - `$updatedAt` string, date-time, nullable
    - `$contractValue` number, nullable: The contract value of the contact.
  - `account` Account
    - `id` string, required: The unique identifier for the account.
    - `shouldUnflattenProperties` boolean, nullable: Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`
    - `properties` object
      - `$name` string, required: The name of the account.
      - `$domain` string, required: The domain of the account.
      - `$createdAt` string, date-time, nullable
      - `$updatedAt` string, date-time, nullable
      - `$contractValue` number, nullable: The contract value of the account.
  - `source` string, nullable: Source system to limit search to

## Response `201`

The customer was identified successfully

- object
  - `success` boolean

## Changes

- **2025-10-20** `2047ff338631`: 2 info
  - added the new optional request property `properties/$contractValue`
  - added the new optional request property `source`
- **2025-02-26** `f8820abd2c00`: 1 info
  - added the new optional request property `account`
- **2025-02-23** `8caf09b237e7`: 1 info
  - added the new optional request property `shouldUnflattenProperties`
- **2025-02-11** `40c9b511d382`: 2 info
  - added the new optional request property `properties/$createdAt`
  - added the new optional request property `properties/$updatedAt`
- **2025-02-11** `1a782c324c03`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api/changes/contacts/identify/post.md)

---

[API](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api.md) - [All operations](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/monterey-ai/apis/reforge-insights-formerly-monterey-ai-api/revisions/fd623cac2355?raw)
