Identify

Link external records to people and companies

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

  • Base URL: https://api.modem.dev/v1
  • URL: https://api.modem.dev/v1/identify
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Replays a successful mutating request for 24 hours. Reuse with a different payload returns 409.

Request body

Response

OK

Changes

No recorded changes to this operation across all 1 revision of this API.