Promote an identity

Some businesses identify a person with a temporary id first, such as a lead id during onboarding, and issue a permanent id later, such as a client code. Promote the identity when the permanent id exists. The profile keeps its history.

POST https://api.true-engage.com/v1/users/identity/promote

What it does

• Binds the new id to the profile and makes it the profile's external id.
• If another profile already holds the new id, the two profiles are merged. The surviving profile shows the full history of both: activity, event counts, audience conditions and computed attributes include events recorded before the merge.
• Both ids keep resolving afterwards, so an app that still sends the old id keeps working.

Authentication

A server key or Data API key with scope data.merge_user. See Authentication.

Request body

Field	Type	Required	Notes
fromExternalId	string	Yes	The id the profile has today. 1 to 256 characters.
toExternalId	string	Yes	The permanent id. 1 to 256 characters.

Example

curl -X POST https://api.true-engage.com/v1/users/identity/promote \
  -u "test_xxxxxxxx:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fromExternalId": "lead:9f3c21", "toExternalId": "C10093" }'

const auth = Buffer.from(`${process.env.TE_APP_KEY}:${process.env.TE_SECRET}`).toString('base64');

const res = await fetch('https://api.true-engage.com/v1/users/identity/promote', {
  method: 'POST',
  headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ fromExternalId: 'lead:9f3c21', toExternalId: 'C10093' }),
});
const { data } = await res.json();
console.log(data.outcome); // linked | merged | noop

Response

Status 200 OK.

{
  "requestId": "0b1c6f2e-6a1d-4c58-9f47-2b7d6d1f8a10",
  "data": { "userId": "3d2c1b0a-5e4f-4a3b-9c8d-7e6f5a4b3c2d", "outcome": "linked" }
}

outcome	Meaning
linked	The permanent id was attached to the profile.
merged	Another profile held the permanent id, and the two were merged. userId is the surviving profile.
noop	The profile already has this id. Nothing changed.

The call is idempotent, so it is safe to retry.

Errors

Status	Code	Cause
404	USER_NOT_FOUND	No profile has fromExternalId.
409	IDENTITY_PROMOTION_BUSY	Another promotion of this id is in progress. Retry in a moment.
429	RATE_LIMITED	Over 600 requests per minute per key.
401 or 403	INVALID_API_KEY, INSUFFICIENT_SCOPE, KEY_KIND_NOT_ALLOWED	Credential problem.

See Errors.