Skip to main content
platform

Quick Start

active
Audience: developerUpdated 2026-07-26

This is the fastest way to get data flowing into Binoban. You'll learn what a source is, create one in the panel to get its credentials, and make your first API call — sending a tracking event and (for Retail Media) syncing a product.

We use curl here because it needs no setup and works against any deployment. If you'd rather start from an SDK, the SDK paths are linked at the end.

Step 1 — Understand sources​

Everything you send to Binoban goes through a source: one origin of data — a website, a mobile app, or a backend service. Each source carries two values that every request needs:

  • a sourceIdentifier, which routes data to the right source, and
  • an apiKey, which authenticates the request.

You pick the source type that matches where your data comes from:

Source typeWhat it isUse it when
Tracking REST APIServer-to-server HTTPSending trusted events from your backend (orders, payments, server-side state)
Web SDKJavaScript for the browserTracking a website or web app
Android SDKNative (Kotlin Multiplatform)Tracking an Android app
iOS SDKNative (Kotlin Multiplatform)Tracking an iOS app
Catalog APIREST for catalog syncFeeding products, variants, and categories for Retail Media

The first four are for tracking customer data (identity + behaviour). The Catalog API is the entry point for Retail Media — it syncs your product catalog rather than user events.

Step 2 — Create a source and get your credentials​

Credentials are issued per source in the Product Workspace:

  1. Open Data → Data Sources.
  2. Add a source and choose the type you need (Web SDK, Android/iOS SDK, or a server API for REST/Catalog).
  3. Open the new source and go to its Settings to find its apiKey and sourceIdentifier.

You'll also need your apiHost — the base URL your requests go to. On Binoban cloud that's https://api.binoban.io; on an on-prem or air-gapped deployment it's your own server's address. The examples below use the cloud host — replace it with your apiHost.

note

Data sources are created and managed in the Data module of the Product Workspace. For how credentials and the Bearer header work in full, see Authentication & setup.

Step 3 — Track your first event​

A track call records something a user did. Send a POST to the tracking endpoint for your source, authenticating with your apiKey as a Bearer token:

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": "user_123",
    "event": "product_added",
    "properties": {
      "sku": "SKU-42",
      "price": 14.99
    }
  }'
  • userId identifies the person. Before you know who they are, you can send an anonymousId instead — one of the two is required.
  • event is the action's name; properties is free-form context.

To attach traits to a person (name, email, plan), use the companion identify call — POST …/identify with a traits object. See the Identify spec and the full Tracking API reference for every field.

Step 4 — Sync your first product​

If you're activating Retail Media, your catalog is the substrate ads are built on. Sync a product with the Catalog API — same Bearer auth, a different endpoint:

curl --location 'https://api.binoban.io/api/tracker/catalog/YOUR_SOURCE_IDENTIFIER/product' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "productId": "shoe123",
    "name": "UltraBoost Sneakers",
    "categoryId": "cat456",
    "mainImage": "https://cdn.example.com/images/shoe123-main.jpg",
    "totalStock": 100,
    "isAvailable": true,
    "url": "https://www.example.com/products/ultraboost-sneakers"
  }'

A successful sync returns:

{ "status": "QUEUED" }

QUEUED means Binoban accepted the product for processing. Products, variants, categories, and sellers each have their own endpoint — see the full Sync API reference.

Step 5 — Confirm it worked​

  • Tracking returns 200 when the event is accepted.
  • Catalog returns 200 with { "status": "QUEUED" }.

If you get a 401, the apiKey is wrong or missing. If the request fails to connect at all, check your apiHost. A success means Binoban accepted the call — it then flows into your source, where your team works with the data under Data in the Product Workspace.

Verifying downstream

A 200 means the call was accepted, not that it has finished processing downstream. A dedicated in-workspace event inspector is being documented separately.

Prefer an SDK?​

curl is the quickest way to a first call, but for real integrations the SDKs handle batching, retries, identity, and offline queueing for you. Each follows the same source/credentials model from Step 2:

Next steps​

Last updated on