Tracking API

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:

Header	Value
Authorization	Bearer YOUR_API_KEY
Content-Type	application/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.

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"
}

Field		Type	Description
anonymousId	required; optional if userID is set instead	String	A pseudo-unique substitute for a User ID, for cases when you don't have an absolutely unique identifier. A userId or an anonymousId is required.
userId	required; optional if anonymousID is set instead	String	Unique identifier for the user in your database. A userId or an anonymousId is required.
context	optional	Object	Dictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale.
traits	optional	Object	Free-form dictionary of traits of the user, like email or name.
timestamp	optional	Date	Timestamp 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.

Field		Type	Description
anonymousId	required; optional if userID is set instead	String	A pseudo-unique substitute for a User ID, for cases when you don't have an absolutely unique identifier. A userId or an anonymousId is required.
userId	required; optional if anonymousID is set instead	String	Unique identifier for the user in your database. A userId or an anonymousId is required.
context	optional	Object	Dictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale.
event	required	String	Name of the action that a user has performed.
properties	optional	Object	Free-form dictionary of properties of the event, like revenue.
timestamp	optional	Date	Timestamp 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.

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.

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.