Identify User

Create or update a user and their traits from your backend with POST /v2/admin/identify-user.

Create or update a user and sync traits from your backend. This is the server-to-server counterpart of SDK identifyUser — same identify pipeline, admin key only, and no in-app form payload.

Use it when traits live in backend systems (plan, company, billing) rather than in the client. For keys, auth, and rate limits, see Admin API Reference.

POSThttps://api.encatch.com/engage-product/encatch/api/v2/admin/identify-user

Authentication

X-Api-KeystringRequired

Admin (secret) API key

Content-TypestringRequired

Request body format

application/json

Publishable SDK keys receive 403 (publishable API keys cannot call /v2/admin routes).

Server-side only

Keep admin API keys on your server. Never ship them in client code.

Request body

Maximum body size: 100 KB (413 if larger).

userNamestringRequired

Unique user identifier — email, internal id, or ASCII username. Empty or missing returns 401. Prefer 1–50 characters: letters, digits, and . _ @ -. Store display names with spaces or non-ASCII characters as traits, not as the user name.

userAttributesobject

Trait operations to apply to this user.

$setobject

Set or overwrite traits.

$setOnceobject

Set a trait only if it is not already set.

$incrementobject

Increment numeric traits.

$decrementobject

Decrement numeric traits.

$unsetstring[]

Trait keys to remove.

$deviceInfoobject

Optional device metadata. For admin identify, country code is the useful field. Invalid country codes return 400.

Show 16 properties

$countryCodestring

ISO 3166-1 alpha-2. Invalid value returns 400 (invalid country passed).

$timezonestring

IANA timezone

$deviceOsstring

Device operating system

iOSAndroidWindows

$deviceOsVersionstring

OS version

$sdkVersionstring

Client SDK version

$appstring

Application identifier

$appVersionstring

Application version

$deviceLanguagestring

Device locale, e.g. en-US

$userLanguagestring

User language, e.g. en

$deviceIdstring

Device identifier

$urlOrScreenNamestring

Current URL or screen name

$deviceTypestring

Client surface

webnative

$deviceSizestring

Viewport class

desktoptabletmobile

$preferredThemestring

Color scheme

lightdark

$browserstring

Browser name

$browserVersionstring

Browser version

userSignaturestring

SDK HMAC field. Not required for admin identify.

Trait limits

Limit	Value
Trait key length	100 characters
Trait string value length	500 characters

Exceeding either limit returns 400.

Trait policy

New traits — Admin identify registers unknown slugs even when the project has client-created traits turned off.
Disabled traits — Slugs marked disabled are still dropped.
Usage cap — The unique-traits limit still applies. New slugs over the cap are stripped.
PII allow-list — Known device and PII fields are still filtered. Custom traits pass through.

Same trait operations as SDK identify. Most device-info fields are SDK-oriented — send country code when you know the user's country. Admin identify does not GeoIP-fill country from the caller’s server IP.

Examples

cURL

curl -X POST 'https://api.encatch.com/engage-product/encatch/api/v2/admin/identify-user' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "userName": "alice@example.com",
    "userAttributes": {
      "$set": { "plan": "pro", "company": "Acme" },
      "$setOnce": { "signup_source": "billing" },
      "$increment": { "seats": 1 },
      "$unset": ["trial_ends_at"]
    }
  }'

Minimal body

{ "userName": "alice@example.com" }

Success response

200Response

{
  "message": "ok",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

messagestringRequired

Status. ok on success.

userIdstring

UUID for this organization, project, and user name. Available immediately.

Trait writes are applied asynchronously after this response. Admin identify does not return SDK-only fields (pingAgainIn, pingOnNextPageVisit, nextFeedbackId, onPageDelay).

Errors

These are specific to Identify User. Shared Admin API errors — invalid API key, publishable key (403), rate limits (429), and 500 — are on Admin API Reference.

400Error

{
  "status": 400,
  "error": "Bad Request",
  "message": "invalid country passed"
}

Status	When
`400`	Invalid `$countryCode`; trait key longer than 100 characters or string value longer than 500
`400`	Project MAU quota exhausted (`Monthly active users limit reached for your plan`)
`401`	Missing or empty `userName` (`userName not found`)
`413`	Request body larger than 100 KB

Admin vs SDK identify

	Admin `POST /v2/admin/identify-user`	SDK `POST /v2/encatch/identify-user`
Key	Admin / secret (`X-Api-Key`)	Publishable SDK key
Form to show	Never	May return `nextFeedbackId`
New traits	Registered even if client-created traits are disabled	Honors `allowNewTraitsFromClient`
GeoIP from caller IP	No	Yes

Admin API Reference — auth, base URL, sandbox and live rate limits
Identify & track users (Web SDK)
User Traits

Identify User

On this page