Skip to main content
api

Tracking API

draft
Audience: developerUpdated 2026-10-05

Exhaustive reference for the Tracking REST API — every endpoint, field, and limit. For what server-side tracking is for and a working quickstart, see Track from your backend.

Base URL​

Production is https://api.binoban.io. On-prem and air-gapped deployments use their own apiHost instead.

Authentication​

Every request needs two headers:

HeaderValue
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/json
curl --location 'https://api.binoban.io/api/tracker/sdk/YOUR_SOURCE_IDENTIFIER/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{ "userId": "123", "event": "example_event" }'

Replace YOUR_SOURCE_IDENTIFIER in the URL and YOUR_API_KEY in the header with your own values. See Authentication & setup for how credentials work, and Error codes for the 401/404 failure modes.

Field limits​

User/anonymous IDs and custom event/attribute names are capped at 64 characters with a restricted character set; property and trait values have their own type ranges. Names or IDs that break the rules reject the call; out-of-range values are dropped from the event. See Limits & validation for the full contract and the rejection error codes.

Reserved names​

A handful of property and trait names belong to Binoban — cx_*, eventName, eventTime and receiveTime on track; userId, anonymousId, the *Reachable flags and ct_* on identify. A field sent under one of them is dropped from the call and the rest of the call is processed normally.

The bb_ event-name prefix is reserved too: it is Binoban's system-event namespace, so don't name a track event with it.

See Limits & validation → Reserved names.

Max request size​

A single identify or track request may be at most 8 KB; a batch may carry at most 100 events and 800 KB.

Exceeding either limit rejects the request with 413 Payload Too Large — confirmed behavior, thrown on every ingestion path (single and batch, identify and track). See Error codes for the confirmed error table and Limits & validation for the full contract.

Identify​

Identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them.

Binoban recommends calling Identify a single time when the user's account is first created, and only identifying again later when their traits change.

POST /api/tracker/sdk/YOUR_SOURCE_IDENTIFIER/identify
{
"userId": "019mr8mf4r",
"traits": {
"email": "pgibbons@example.com",
"name": "Peter Gibbons",
"industry": "Technology"
},
"context": {
"ip": "24.5.68.47"
},
"timestamp": "2012-12-02T00:30:08.276Z"
}

At least one identifier from your workspace's identity strategy is required. By default that is userId, anonymousId or a device id in context.device; phone, email and custom-trait identifiers count once they are enabled in the strategy. See Identity Strategy.

FieldTypeDescription
anonymousIdoptional; required only if the call carries no other identifierStringA pseudo-unique substitute for a User ID, for cases when you don't have an absolutely unique identifier.
userIdoptional; required only if the call carries no other identifierStringUnique identifier for the user in your database.
contextoptionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale.
traitsoptionalObjectFree-form dictionary of traits of the user, like email or name.
timestampoptionalDateTimestamp when the message itself took place, defaulted to the current time by the Binoban Tracking API, as an ISO-8601 format date string. If the event just happened, leave it out and the server will use its own time. If you're importing data from the past, provide a timestamp.

Track​

Track lets you record the actions your users perform. Every action triggers an "event", which can also have associated properties.

You'll want to track events that are indicators of success for your site, like signed_up, item_purchased, or article_bookmarked. Event names must match ^[a-zA-Z0-9_\-.]*$ — no spaces; use snake_case, not Title Case.

POST /api/tracker/sdk/YOUR_SOURCE_IDENTIFIER/track
{
"userId": "019mr8mf4r",
"event": "item_purchased",
"properties": {
"name": "Leap to Conclusions Mat",
"revenue": 14.99
},
"context": {
"ip": "24.5.68.47"
},
"timestamp": "2012-12-02T00:30:12.984Z"
}

Track event properties can be anything you want to record. In this case, name and revenue.

At least one identifier from your workspace's identity strategy is required. By default that is userId, anonymousId or a device id in context.device; phone, email and custom-trait identifiers count once they are enabled in the strategy. See Identity Strategy.

FieldTypeDescription
anonymousIdoptional; required only if the call carries no other identifierStringA pseudo-unique substitute for a User ID, for cases when you don't have an absolutely unique identifier.
userIdoptional; required only if the call carries no other identifierStringUnique identifier for the user in your database.
contextoptionalObjectDictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale.
eventrequiredStringName of the action that a user has performed.
propertiesoptionalObjectFree-form dictionary of properties of the event, like revenue.
timestampoptionalDateTimestamp when the message itself took place, defaulted to the current time by the Binoban Tracking API, as an ISO-8601 format date string. If the event just happened, leave it out and the server will use its own time. If you're importing data from the past, provide a timestamp.

Identify Batch​

Send multiple Identify calls in a single request instead of one call per request. The body is an object with a required list array — not a bare top-level array. list must contain 1 to 100 items, and is subject to the same max request size as any other batch: 800 KB.

POST /api/tracker/sdk/YOUR_SOURCE_IDENTIFIER/identifyBatch
{
"list": [
{
"userId": "019mr8mf4r",
"traits": { "email": "jake@example.com", "name": "Jake Peterson" },
"timestamp": "2012-12-02T00:30:08.276Z"
},
{
"userId": "971mj8mk7p",
"traits": { "email": "cindy@example.com", "name": "Cindy Gonzalez" },
"timestamp": "2012-12-02T00:30:09.104Z"
}
]
}

Each element of list takes the same fields as a single Identify call.

Every event in the batch must carry an identifier. If any event does not, the whole batch is rejected with error.sdk.missing.identifier and nothing is stored.

Track Batch​

Send multiple Track calls in a single request. The body is an object with a required list array — not a bare top-level array. list must contain 1 to 100 items, and is subject to the same max request size as any other batch: 800 KB.

POST /api/tracker/sdk/YOUR_SOURCE_IDENTIFIER/trackBatch
{
"list": [
{
"userId": "019mr8mf4r",
"event": "song_played",
"properties": { "name": "Fallin for You", "artist": "Dierks Bentley" },
"timestamp": "2012-12-02T00:30:12.984Z"
},
{
"userId": "971mj8mk7p",
"event": "song_played",
"properties": { "name": "Get Right", "artist": "Jennifer Lopez" },
"timestamp": "2012-12-02T00:30:13.512Z"
}
]
}

Each element of list takes the same fields as a single Track call.

Every event in the batch must carry an identifier. If any event does not, the whole batch is rejected with error.sdk.missing.identifier and nothing is stored.

Historical import​

You can import historical data by adding the timestamp argument to any of your method calls. This can be helpful if you've just switched to Binoban.

info

If you're tracking things that are happening right now, leave out the timestamp and Binoban servers will timestamp the requests for you.