---
search:
  tags:
    - Identify
    - POST
seo:
  description: >-
    Idempotently link external platform records (e.g. Stripe customers) to Modem
    people and companies. Reference for the POST /identify endpoint in the Modem
    API.
sidebar:
  label: Link external records to people and companies
  badge: POST
title: Link external records to people and companies
type: openapi-operation
---
Idempotently link external platform records (e.g. Stripe customers) to Modem people and companies.

Each `person` / `company` block states the facts the platform knows about that side of the record — not an assertion of how to resolve it. Modem owns all matching.

**Person** — matched by platform `identity` first, then by exact `email`. A bare email matches an existing person but never creates one (it may be a shared inbox like billing@); creation requires `displayName`.

**Company** — matched by the first hit, in trust order:

1. an existing platform `identity` link for this block
2. the resolved person's current company
3. stated `domains`, then the domain derived from `person.email` (free-mail domains such as gmail.com carry no signal)
4. an exact, case-insensitive `name` match
5. otherwise created — only when `name` is stated

When both a person and a company resolve, their membership is recorded.

If the platform identity and a natural key (email/domain) resolve to different entities, the identity match wins and nothing is merged; the other entity is returned as `conflictWith` — a probable duplicate to reconcile deliberately.

Removing a stored link is not part of this endpoint; it will ship separately.

`POST /identify`

**Request body** (`application/json`, required)

- `identifications` (object[], required)

Request body example:

```json
{
  "identifications": [
    {
      "company": {
        "description": "string",
        "domains": [
          "string"
        ],
        "identity": {
          "platform": "string",
          "platformId": "string"
        },
        "logoUrl": "http://example.com",
        "name": "string",
        "overwrite": [
          "description"
        ]
      },
      "person": {
        "avatarUrl": "http://example.com",
        "description": "string",
        "displayName": "string",
        "email": "user@example.com",
        "identity": {
          "platform": "string",
          "platformId": "string"
        },
        "overwrite": [
          "avatarUrl"
        ]
      }
    }
  ]
}
```

**Responses**

- `200` — OK
- `400` — Invalid request (validation failed).
- `401` — Missing or invalid API key.
- `403` — The API key does not have access to this resource.
- `404` — The requested resource was not found.
- `409` — The request conflicts with an existing resource or idempotency operation.
- `429` — Rate limit exceeded.
- `500` — Internal server error.

Response example, 200:

```json
{
  "results": [
    {
      "company": {
        "conflictWith": "string",
        "created": true,
        "id": "string"
      },
      "membershipLinked": true,
      "person": {
        "conflictWith": "string",
        "created": true,
        "id": "string"
      }
    }
  ]
}
```