Skip to main content
sdk

Identify

active
Audience: developerUpdated 2026-10-05

The Identify call ties an identity to a set of traits — everything you know about a person: their name, email, plan, or any custom attribute your business tracks. Together with Track, it is the whole tracking contract: Track records what someone did, Identify records who they are.

Binoban recommends calling Identify:

  • After a user first registers
  • After a user logs in
  • When a user updates their info (for example, they change or add a new address)

Calling Identify is one of the first steps in integrating a Binoban library. Refer to the library-specific SDK pages for the exact call shape.

Example​

A minimal Identify call needs only an identity and one or two traits:

{
"type": "identify",
"userId": "97980cfea0067",
"traits": {
"name": "Peter Gibbons",
"email": "peter@example.com",
"plan": "premium",
"logins": 5
}
}

The matching Web SDK call:

Binoban.identify("97980cfea0067", {
name: "Peter Gibbons",
email: "peter@example.com",
plan: "premium",
logins: 5,
});

A fuller payload, showing the fields you'll see on most real calls:

{
"type": "identify",
"userId": "97980cfea0067",
"anonymousId": "b7e1c9f0-6b2a-4e9a-9c3d-2f6a1d9e4b71",
"timestamp": "2026-07-26T14:32:00.000Z",
"traits": {
"firstName": "Peter",
"lastName": "Gibbons",
"email": "peter@example.com",
"plan": "premium",
"logins": 5
},
"context": {
"ip": "8.8.8.8",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
}
}

Identities​

Every Identify call carries at least one identifier from your workspace's identity strategy: userId, anonymousId, a device id in context.device, or (when enabled in the strategy) phone, email or a custom identifier trait in traits. It's the same rule that governs Track, since both calls validate identity the same way:

FieldRequired?Max lengthAllowed characters
userIdOptional; one identifier required64a–z A–Z 0–9 _ - . @ :
anonymousIdOptional; one identifier required64a–z A–Z 0–9 _ - . @ :

A call with no identifier is rejected with error.sdk.missing.identifier. An empty string does not count. If the only identifier is a phone or email that fails the format check, it is dropped and the call is rejected. A value using disallowed characters rejects it with error.sdk.user.id.pattern / error.sdk.anonymous.id.pattern; a value over 64 characters also rejects the call, but the exact code that response carries isn't confirmed — the length check runs through generic validation, not the pattern check that's wired to those codes. See Limits & validation for the full rejection table.

Anonymous ID​

There are cases where you don't know who the user is according to your database, but you still want to tie them to traits, events, or page views — for example, tracking a newsletter signup or an anonymous page view before sign-in.

In these cases, use an Anonymous ID. It can be any pseudo-unique identifier — a session id, for example. If you don't have one readily available, generate a new random one; Binoban recommends UUIDv4 format.

info

Binoban's browser and mobile libraries automatically manage Anonymous IDs as users navigate your site or app, so you don't need to generate or persist one yourself when using those libraries.

Here's an example Identify call for an anonymous user:

Binoban.identify({
subscriptionStatus: "inactive",
});

User ID​

User IDs are a more permanent identifier, like a database ID. Since they're consistent across a customer's lifetime, Identify calls should include a User ID as often as possible.

A User ID is usually the identifier you already recognize a user by in your own database — for example, a MongoDB document id like 507f191e810c19729de860ea.

Binoban recommends using a database ID as the User ID rather than an email address or username, because a database ID doesn't change even if the person later changes their email or username — so you can keep recognizing them as the same person across every tool that reads Binoban data.

success

Instead of using an email address or a username as the User ID, send them along as traits.

Traits​

traits is an optional, free-form dictionary describing the person — name, plan, logins, or any custom attribute your business tracks. This is the point of Identify: give Binoban traits once, and every event tied to that identity can be understood in terms of them.

Trait names (keys) follow the same rule as event and property names:

RuleValue
Max length64 characters
Allowed charactersa–z A–Z 0–9 _ - .

A trait name over the limit or with disallowed characters rejects the whole call (error.sdk.attribute.name.length / error.sdk.attribute.name.pattern).

Reserved traits​

Binoban recognizes a small set of trait names as reserved: sent under these exact keys, they map onto known fields on the person's profile instead of being stored as an arbitrary custom attribute. They are yours to write — writing them is what Identify is for. (A smaller set of names is read-only and can't be written at all; see Read-only traits below.) Five of the writable ones also carry an enforced length limit at ingestion — a value over the limit is silently dropped from the call, the same as any other out-of-range trait value (see Limits & validation → System traits):

TraitTypeMax length
firstNameString32
lastNameString32
emailString64
companyString64
jobTitleString64

If you've integrated Segment-style tools before, two things differ here: company is a plain string (a name), not an object with sub-fields, and the job-title trait is named jobTitle, not title.

Binoban's profile model recognizes four more scalar reserved traits, but none of them carry a length limit of their own — an out-of-range value falls back to the generic value rules in Limits & validation → Value limits:

TraitType
phoneString
genderOne of MALE, FEMALE, OTHER — matched case-insensitively, so "female" also works
birthdayDate — stored as a timestamp, not a free-form string; send an ISO 8601 date
timezoneString

Five last reserved traits are booleans that each gate whether Engage may contact this person on one channel — set one to false to opt the person out of that channel, or true to opt them back in. An unset flag behaves as opted-in.

TraitEngage channel
smsOptInSMS
emailOptInEmail
pushOptInPush
webPushOptInWeb push
customOptInCustom channel

SMS and email sends also require the person to actually have a phone or email trait set — opting someone in on a channel with no contact info on file still won't reach them.

warning

Only send firstName, lastName, email, company, jobTitle, phone, gender, birthday, and timezone when the value actually means what the name says, and only flip an opt-in trait when you mean to change that person's consent for that channel — Binoban's profile model and Engage act on these values directly.

Read-only traits​

A second set of names is owned by Binoban and can't be written from an Identify call: the identity the call already carries, the reachability flags Binoban derives for itself, and the computed-trait namespace. A trait sent under one of these is dropped from the call:

TraitWhySend instead
userIdIdentity is carried by the call itself.userId at the top level of the call
anonymousIdIdentity is carried by the call itself.anonymousId at the top level of the call
smsReachableReachability is derived — from the contact details on the profile, the device registrations, and the opt-in trait.smsOptIn
emailReachableDerived.emailOptIn
pushReachableDerived.pushOptIn
webPushReachableDerived.webPushOptIn
customReachableDerived.customOptIn
Any name starting with ct_The prefix belongs to computed traits, which your workspace calculates rather than receives.Define a computed trait in the workspace

Only the reserved trait is removed — the rest of the Identify call is processed normally, so the profile still gets every other trait in the payload.

Custom traits​

Every other trait name — including some you may expect from other analytics tools, like name, id, address, avatar, age, createdAt, description, title, username, or website — is a plain custom trait to Binoban. Send them if they're useful for your own reporting; Binoban stores them, but attaches no special meaning or handling to the name itself.

Traits as identity matching keys​

Any trait — reserved or custom — can be configured as an identity matching key for your workspace, so that events carrying the same value resolve to one profile. Phone and email matching are not enabled by default; ask your Binoban team to turn them on if your integration depends on them. See Identity strategy → What's on by default.

Context​

context on an Identify call is the same object documented in Track → Context — environment and identity-adjacent data about where the call came from (page, device, campaign, and so on).

The one real difference: Identify writes profile traits only from the top-level traits field, not from context.traits. context.traits is how a Track or Page call carries traits collected on an earlier Identify call alongside an event; Identify is the call that sets those traits in the first place, so it doesn't need the nested form. For identity matching, a phone, email or custom identifier trait missing from traits is also read from context.traits.

See Track for the shared context shape, and Identity strategy for how Binoban uses userId, anonymousId, and traits together to resolve events to one profile.