Tradable Bits - Collect First Party Data, Centralize Your Marketing, Activate at Scale.

Developers

Our platform was built to be flexible and intuitive for developers like you. You own all the data you collect with Tradable Bits. Our API and SDK are designed to make it easy to access your fan data, tickets and campaigns at any time, on your terms Customize the front end of any of your campaigns with the help of our documentation, complete with examples. Our RESTful API helps you access, send or receive fan data from our system to your endpoints quickly and securely. Enrich your Fan CRM and Tickets Analytics with data from other CRM systems through our many integrations. Have any questions about our developers platform? Our support team is happy to help.

Website Integration

Overview

The Tradable Bits API allows you to fully integrate authentication, fan profiles, and content into your website or application. This guide covers how to authenticate fans, manage sessions, and interact with the API from your server-side code.

Examples are written in Python using the requests library, but any server-side language can be used.

Terms and Values

`api_key`	Public API key for your account. Used in all API requests.
`api_secret`	Secret key used to exchange an OAuth authorization code for a session. Never expose this in client-side code.
`business_id`	Identifies a specific business (team) within your account. Required for the Sessions/Connect API.
`session_uid`	A UUID returned after successful authentication. Used in subsequent API calls to identify the logged-in fan.

Account Configuration

Before displaying a login form, retrieve your account's branding and legal information. This returns terms of service, privacy policy, header text, and logo image for use in your UI.

import requests

api_key = "your-api-key"
data = {"api_key": api_key}
res = requests.post("https://nest.tradablebits.com/api/v1/status", data=data)
if res.status_code == 200:
    result = res.json()
    legal_terms = result.get("legal_terms")
    legal_privacy = result.get("legal_privacy")
    header_text = result.get("header_text")
    image_url = result.get("image_url")
else:
    print("Error:", res.text)

Option 1: OAuth Login

The OAuth flow redirects the fan to Tradable Bits for authentication, then back to your callback URL with an authorization code. You exchange the code for a session on the server side.

Step 1: Add a login link on your website that redirects to the OAuth endpoint:

<a href="https://nest.tradablebits.com/crm/oauth?account_id=YOUR_ACCOUNT_ID&business_id=YOUR_BUSINESS_ID&login_type=email&redirect_url=https://www.example.com/auth_callback">
    Sign in with Email
</a>

Step 2: On your callback URL, exchange the authorization code for a session:

import requests

def process_callback(request):
    code = request.args.get("code")
    error = request.args.get("error")
    if error:
        return handle_error(error)

    params = {
        "code": code,
        "api_key": "your-api-key",
        "account_id": "your-account-id",
        "redirect_url": "https://www.example.com/auth_callback",
    }
    res = requests.get("https://nest.tradablebits.com/crm/access_token", params=params)
    if res.status_code == 200:
        session = res.json()
        session_uid = session["session_uid"]
        fan_id = session["fan_id"]
        handle_session(session_uid, fan_id)
    else:
        print("Error:", res.text)

Option 2: Sessions/Connect API

The Sessions/Connect API gives you full control over the authentication flow without redirecting the fan away from your site. All requests go to the same endpoint, with the network parameter controlling the step.

Endpoint: POST https://nest.tradablebits.com/api/v1/sessions/connect

All requests require api_key and business_id.

Step 1: Check if Fan Exists

Check whether the fan's email or phone is already registered. The response tells you whether to proceed with login or registration.

import requests

# Check by email (network=email) or phone (network=phone)
data = {
    "api_key": "your-api-key",
    "business_id": "your-business-id",
    "network": "email",
    "email": "fan@example.com",
}
res = requests.post("https://nest.tradablebits.com/api/v1/sessions/connect", data=data)
if res.status_code == 200:
    result = res.json()
    if result["status"] == "register":
        print("Fan not found — proceed to registration")
    elif result["status"] == "login":
        print("Fan exists — proceed to login")
        has_phone = result.get("phone", False)
        has_password = result.get("password", False)
else:
    print("Error:", res.text)

Step 2: Send Verification Code

Send a one-time verification code via email or SMS. Use network=verify_email or network=verify_sms.

import requests

data = {
    "api_key": "your-api-key",
    "business_id": "your-business-id",
    "network": "verify_email",  # or "verify_sms"
    "email": "fan@example.com",
}
res = requests.post("https://nest.tradablebits.com/api/v1/sessions/connect", data=data)
if res.status_code == 200:
    result = res.json()
    request_uid = result["request_uid"]
    print(result["message"])  # "Verification code has been sent to ..."
else:
    print("Error:", res.text)

Step 3: Submit Verification Code

After the fan receives the code, submit it along with the request_uid from Step 2.

import requests

data = {
    "api_key": "your-api-key",
    "business_id": "your-business-id",
    "network": "submit_verification_code",
    "email": "fan@example.com",
    "verification_code": "49270",
    "request_uid": "request-uid-from-step-2",
}
res = requests.post("https://nest.tradablebits.com/api/v1/sessions/connect", data=data)
if res.status_code == 200:
    result = res.json()
    if result.get("session_uid"):
        session_uid = result["session_uid"]
        fan_id = result["fan_id"]
        print("Login successful:", session_uid)
    elif result.get("status") == "register":
        # Fan verified but not yet registered — proceed to Step 4
        print("Verification successful, registration required")
else:
    print("Error:", res.text)

Step 4: Register New Fan

If the fan doesn't exist yet, register them. If a verification was completed (Step 2-3), include the request_uid and verification_uid to skip re-verification.

import requests

data = {
    "api_key": "your-api-key",
    "business_id": "your-business-id",
    "network": "register",
    "email": "fan@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    # Include these if verification was completed in Steps 2-3:
    "request_uid": "request-uid-from-step-2",
    "verification_uid": "verification-uid-from-step-3",
}
res = requests.post("https://nest.tradablebits.com/api/v1/sessions/connect", data=data)
if res.status_code == 200:
    result = res.json()
    if result.get("session_uid"):
        # Registration + verification complete — session created
        session_uid = result["session_uid"]
        fan_id = result["fan_id"]
        print("Registered and logged in:", session_uid)
    elif result.get("status") == "login":
        # Registered without verification — now prompt for login
        print("Registered. Prompt fan to verify via email or SMS.")
else:
    print("Error:", res.text)

Password Login

If the fan has a password set (password: true from Step 1), they can log in directly.

import requests

data = {
    "api_key": "your-api-key",
    "business_id": "your-business-id",
    "network": "password",
    "email": "fan@example.com",
    "password": "their-password",
}
res = requests.post("https://nest.tradablebits.com/api/v1/sessions/connect", data=data)
if res.status_code == 200:
    result = res.json()
    session_uid = result["session_uid"]
    fan_id = result["fan_id"]
    print("Login successful:", session_uid)
else:
    print("Invalid login:", res.text)

Session Management

Once you have a session_uid, you can retrieve the session and manage the fan's profile.

Get Session

import requests

session_uid = "session-uid-from-login"
params = {"api_key": "your-api-key"}
res = requests.get(f"https://nest.tradablebits.com/api/v1/sessions/{session_uid}", params=params)
if res.status_code == 200:
    session = res.json()
    print("Session:", session)
else:
    print("Error:", res.text)

Get Fan Profile

import requests

session_uid = "session-uid-from-login"
params = {"api_key": "your-api-key"}
res = requests.get(f"https://nest.tradablebits.com/api/v1/sessions/{session_uid}/fan", params=params)
if res.status_code == 200:
    fan = res.json()
    print("Fan:", fan)
else:
    print("Error:", res.text)

Update Fan Profile

Update the fan's name, password, display name, or other fields.

import requests

session_uid = "session-uid-from-login"
data = {
    "api_key": "your-api-key",
    "first_name": "Jane",
    "last_name": "Doe",
    "password": "new-password",  # optional — set or update password
}
res = requests.post(f"https://nest.tradablebits.com/api/v1/sessions/{session_uid}/fan", data=data)
if res.status_code == 200:
    result = res.json()
    print("Updated:", result)
else:
    print("Error:", res.text)

Idols and Lineup

Retrieve artists/idols for your lineup and manage fan preferences.

Get All Idols

params = {"api_key": "your-api-key", "label_name": "your-label"}
res = requests.get("https://nest.tradablebits.com/api/v1/idols", params=params)

Get Events

params = {"api_key": "your-api-key", "label_name": "your-label"}
res = requests.get("https://nest.tradablebits.com/api/v1/idols/events", params=params)

Get Fan's Liked Idols

session_uid = "session-uid-from-login"
params = {"api_key": "your-api-key", "label_name": "your-label"}
res = requests.get(f"https://nest.tradablebits.com/api/v1/sessions/{session_uid}/idols", params=params)

Add Idol to Liked

session_uid = "session-uid-from-login"
data = {"api_key": "your-api-key", "action": "add", "idol_uid": "idol-uid"}
res = requests.post(f"https://nest.tradablebits.com/api/v1/sessions/{session_uid}/idols", data=data)

Error Handling

The API uses standard HTTP status codes. Common error responses:

400	Bad Request — invalid parameters or validation error. The response body contains a descriptive error message.
401	Unauthorized — invalid `api_key`, expired session, or incorrect credentials.
429	Too Many Requests — rate limit exceeded. Back off and retry after a delay. Some endpoints (e.g., fan lookup) are throttled to prevent enumeration.