Person external associations

Use Contacts REST for ordinary Person creation and reading. If a record comes from a configured source, optionally associate it with that source during the same creation. The Integration identifies the source namespace; externalId identifies a record within it.

Configure the source once

An authorized Integration editor adds an External source in the token's Project under Settings → Integrations, names the source and selects existing Project Access Tokens. If no token exists, first create one in Access Tokens settings. Token secrets are never shown in the Integration editor. The selection is stored as properties.personRegistration.projectAccessTokenIds. Missing or empty configuration denies association creation and lookup. This permission is additional to the standard People API access. It does not require a mapper or source-capture configuration.

Existing Data Ingestion associations remain supported. Use Data Ingestion for arbitrary payloads requiring mapping, capture or ingestion processing, not for new standardized direct API sources. There is no automatic conversion between the two Integration types.

When rotating a token, select the replacement token on the same source, update the caller's credential, then remove/revoke the old token. Changing the Integration ID changes the namespace; do not create a replacement Integration merely to rotate credentials. Keep the same Integration and external ID across retries and token rotation. External IDs are exact, case-sensitive strings of 1–255 characters, not whitespace-only and without NUL. They are not trimmed, coerced to numbers or matched against names, email addresses or phone numbers.

Create with an association

Send POST /api/v1/external/people on https://api-external.svit.one with the same bearer header as Contacts REST:

{
    "name": "Ada Lovelace",
    "emails": ["ada@example.test"],
    "phones": ["+380501112233"],
    "externalAssociation": {
        "integrationId": "<integration-uuid>",
        "externalId": "customer-42"
    }
}

All standard Person fields remain supported. The token selects the Project; do not supply a Project or actor in the body. 201 returns the normal safe Person result with its id, only after the Person and association are committed together. Association failure leaves no new Person.

An occupied key returns 409, without creating another Person or updating the existing one, even when the submitted Person fields differ. Concurrent requests for the same key create one Person only. Retired keys and unavailable owners cannot be reclaimed by this operation.

Look up the current Person ID

Use the same Project Access Token and Integration permission:

GET /api/v1/external/people/by-external-id?integrationId=<integration-uuid>&externalId=customer-42
Authorization: Bearer <project-access-token>

URL-encode both query values. 200 returns only:

{ "personId": "person-id" }

Use that ID with the standard Person read operation. Lookup returns the current associated owner, not a replay of an earlier response; its ID can change after a Contact merge. Unknown, retired, archived/deleted or Organization-owned associations all return 404. That response does not establish that a retired key can be reused. Missing Integration authority returns 403.

After a timeout or lost create response, use this exact lookup to recover the ID. If you retry creation, keep the same key: it either creates once or returns 409. A preliminary lookup never replaces server-side duplicate protection. After a 503 concurrent-change response, retry with bounded backoff and the same key. For an unavailable-key conflict, seek operator resolution rather than inventing another key or adopting a Contact by email.

Without externalAssociation, ordinary creation remains non-idempotent and needs no Integration. Associations do not capture source payloads, update existing Contacts or expose source observations.