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.

Tradable Bits Server API

NEVER EXPOSE API SECRET IN NON-SECURE ENVIRONMENT E.G. BROWSER OR MOBILE APP. THIS KEY MUST BE KEPT SECURE ON YOUR SERVER SIDE.

You can access the majority of your CRM data through our HTTP-based API. Requests can supply form data via application/json payload and result will be json as well. Authentication is managed via API Keys. The system recognises two form of keys: Public and Secret. Public is meant to be shared and can be used in insecure environments. Secret key is reserved for server-to-server communications and must be kept private. API Keys can be sent either in the request body as api_key and api_secret or as headers using Api-Key and Api-Secret. You can manage API Keys under the profile section once you log into Tradable Bits.

System will honour an ip address of the request, however if you use server side proxy to generate calls, you can supply originating ip address via X-Forwarded-For or X-Real-Ip headers.

There is a limit to how often you can call the Tradable Bits API. Currently, it's set to 25000 calls per minute. If you need a higher limit, please reach out to us.

This call requires api_secret as an additional parameter.

Calls with Lock icon are meant for data exchange or called from the server side. Each call must include api_secret as either GET or POST parameter.

This call requires api_key as an additional parameter.

Calls with Unlock icon are meant to be integrated into mobile or web applications and require api_key as additional parameter for all requests.

Introduction

Console

Segments

GET /v1/segments GET /v1/segments/<segment_type>/<segment_id>/status GET /v1/segments/<segment_type>/<segment_id>

Crm

Ent

Streams

GET /v1/streams GET /v1/streams/<stream_key>/records POST /v1/streams/<stream_key>/records GET /v1/streams/<stream_key>

Sessions

POST /v1/sessions/wifi_fans GET /v1/sessions/check POST /v1/sessions/signup POST /v1/sessions/connect GET /v1/sessions/<session_uid> GET /v1/sessions/<session_uid>/fan POST /v1/sessions/<session_uid>/fan GET /v1/sessions/<session_uid>/points

Idols

POST /v1/idols GET /v1/idols GET /v1/idols/<idol_uid> GET /v1/idols/events

Reports

GET /v1/reports GET /v1/reports/<report_uid>

Misc

POST /v1/media GET /v1/trackers GET /v1/qrcode GET /v1/trackers/<tracker_id> POST /v1/trackers GET /v1/trackers/events GET /v1/props/<prop_name> POST /v1/yinzcam_subscription GET /v1/account_ad_stats GET /v1/account_ad_stats_by_campaign

Apps

GET /v1/fanxp/<page_tab_id>/leaderboard GET /v1/apps GET /v1/businesses GET /v1/businesses/<business_id> GET /v1/apps/<page_tab_id>/stats GET /v1/fanxp/<page_tab_id>/detailed_stats GET /v1/apps/<page_tab_id>/props GET /v1/apps/<page_tab_id> GET /v1/apps/<page_tab_id>/total_points GET /v1/apps/<page_tab_id>/wager_entries GET /v1/apps/<page_tab_id>/simple_points GET /v1/apps/<page_tab_id>/simple_activities POST /v1/apps/<page_tab_id>/registration/checkin GET /v1/crm/get_updates

Informational

GET /v1/networks

API Console

API Access allows you to query most of your Tradable Bits data, as well as register for push notification from our CRM system. Our API Reference is broken into sections by topic: Campaigns, Stream, CRM, etc.

Each Request must include api_key as parameter. You can generate an API key in the Manage Centre.
You may try most of our API calls here. Your API Key will be automatically appended if available.

Input

https://nest.tradablebits.com/api/v1/

Request Type

API Keys ( usually only one of Key or secret is required)

API KEY

API Secret

Additional Arguments

Add Argument

Results

Generated URL

segment_count	Number of fans associated with the segment.
segment_type	One of: tag, snapshot, or filter
segment_id	Unique identifier for the segment.
segment_name	Name of the segment.

fan_count	Total number of fans in the segment.
email_count	Total number of emails in the segment.
phone_count	Total number of phones in the segment.
phone_subscribe_count	Total number of subscribed phones in the segment.
email_subscribe_count	Total number of subscribed emails in the segment.
last_update_timestamp	Timestamp of the most recent update to a fan in the segment, as unix timestamp.
last_update_timestamp_iso	Timestamp of the most recent update to a fan in the segment, as ISO 8601 timestamp.

search_uid	Has to be supplied to get additional records. Currently, result set may be limited and will return search_uid if paging is required.
limit	Max size of the page. Values from 0 to 10000 are supported, default is 1000.

fan_id	Unique identifier for the fan.
email
phone
first_name
last_name
is_subscribed	Boolean flag on whether there is explicit opt-in into email comm
is_phone_subscribed	Boolean flag on whether there is explicit opt-in into SMS comm
last_update_timestamp	Timestamp of most recent update to the fan, as unix timestamp.
last_update_timestamp_iso	Timestamp of most recent update to the fan, as ISO 8601 timestamp.

campaign_title	Name of custom campaign
property_name	Name of the property to track

API Console

Segments Calls

Crm Calls

Ent Calls

Streams Calls

Sessions Calls

Idols Calls

Reports Calls

Misc Calls

Apps Calls

Informational Calls

account_id
app_type
business_id
creation_timestamp
creation_timestamp_iso
is_active
page_tab_id
timezone
title

min_activity_id	Window Specifier. Will return only activities with activity_id greater than given
max_activity_id	Window Specifier. Will return only activities with activity_id less than given
limit	Optional parameter to specify max row count. Max allowed value is 500, default is 100
page_tab_id	Optional Filter to participants of specific campaign
activity_date	Optional Filter to participants for specific date
include_details	Boolean flag to include additional details: fan, idols, connections. Default = False
performance_uid	Optional Filter to participants for specific performance
activity_type	Optional Filter to participants with specific activity type of 'entry', 'vote', 'download', 'registration', 'login', 'reward', 'cashless', 'access', 'intent', or null

account_id	Tradable Bits Account ID
activity_duration_ms	Time taken to complete the activity in milliseconds
activity_id	Unique Identifier for the activity
app_type	For contests - type of contest
campaign_title	Title of the campaign
creation_timestamp	Timestamp of the activity, as unix timestamp
creation_timestamp_iso	Timestamp of the activity, as ISO 8601 timestamp
details	JSON structure of campaign details (varies by campaign)
device_type	The type of device the fan was using at time of entry.
email	Email as submitted on the activity
fan_id	Unique Identifier for the fan record
first_name	First name as submitted on the activity.
ip_address	IP Address
is_phone_subscribed	Opted in to SMS Marketing
is_subscribed	Opted in to Email Marketing
last_name	Last name as submitted on the activity
page_tab_id	ID of campaign / quest for this activity
phone	Phone as submitted on the activity
country_code	Country Code as submitted on the activity
province	Province as submitted on the activity
city	City as submitted on the activity
metro_area	Metro Area as submitted on the activity
postal_code	Postal Code as submitted on the activity
latitude	Latitude as submitted on the activity
longitude	Longitude as submitted on the activity
user_key	Facebook/Spotify/etc User Key
connection_fan_ids	List of Fan IDs connected to this fan
fan	Fan Structure as per documentation
identifiers	List of Fan Identifier structures as per documentation
idol_names	List of connected Idols
opted_in_business_ids	List of business IDs that the fan is opted in to.
performance_uid	Links to a performance
lookup_id	Used when activity_type is registration to provide a corresponding record in int_registrations
activity_type	One of 'entry', 'vote', 'download', 'registration', 'login', 'reward', 'cashless', 'access', 'intent', or null
props	Optional properties

first_name
last_name
email *
phone
campaign_title
province
city
postal_code
country_code
campaign_title
is_subscribed
is_phone_subscribed
activity_type	Activity type must be one of 'entry', 'vote', 'download', 'registration', 'login', 'reward', 'cashless', 'access', 'intent', or null
lookup_id	Used when activity_type is registration to provide a corresponding record in int_registrations
performance_uid	Optional parameter linking to a performance
props_<property>	You can include optional properties as a set of parameters prefixed with props_

show_hidden	Show fans who are hidden from the public leaderboard in the campaign. Default = False
limit	Limit the number of fans fetched from the leaderboard. Default = 10

rank	Leaderboard rank
fan_id	Unique Identifier for the fan record
display_name
is_hidden	If the fan is hidden from the public leaderboard in the campaign (If applicable)
activity_timestamp	Timestamp of when the fan completed the activity (If applicable)
points	Number of points gained in the campaign (If applicable)
balance	Balance within the campaign (If applicable)
activity_duration_ms	Length of time spent for the campaign activity in ms (If applicable)
correct_count	Number of questions answered correctly (If applicable)

start_date	Window Specifier. Will return only tags with creation timestamp greater than given
end_date	Window Specifier. Will return only tags with creation timestamp less than given

tag_name
tag_id
fan_id
creation_timestamp	Creation timestamp as unix timestamp
creation_timestamp_iso	Creation timestamp as ISO 8601 timestamp
first_name
last_name
email

include_recent_entry	Include latest campaign into payload on result
include_business_opt_ins	Include business opt ins into payload on result
name	Email, Phone, Display Name, or Fan ID of a fan.
crm_active_days
crm_inactive_days
crm_start_active_date
crm_end_active_date
fan_youngest_age
fan_oldest_age
fan_incl_snapshot_uids
fan_excl_snapshot_uids
fan_tags
include_tags	Include fan tags into payload on result
fan_tag_relations	Whether to include fans with tags related to those supplied in 'fan_tags' field
fan_networks
fan_only_filter	List. When given, search will return results where the given values are not null (or true). Valid Options are: 'is_subscribed', 'is_optout', 'is_phone_subscribed', 'phone', 'birth_date', 'gender', 'fan_source', 'country_code', 'province', 'metro_area', 'city', 'postal_code', 'latitude'
fan_not_only_filter	List. When given, search will return results where the given values are null (or false). Valid Options are: 'is_subscribed', 'is_optout', 'is_phone_subscribed', 'phone', 'birth_date', 'gender', 'fan_source', 'country_code', 'province', 'metro_area', 'city', 'postal_code', 'latitude'
fan_postal_codes
fan_radius_longitude	A valid longitude. Ex. 45.501. Must be accompanied by fan_radius_latitude and fan_radius_km.
fan_radius_latitude	A valid latitude. Ex. -73.57. Must be accompanied by fan_radius_longitude and fan_radius_km.
fan_radius_km	Must be given when supplying a single fan_postal_codes or when supplying a fan_radius_longitude and fan_radius_latitude
fan_provinces
fan_rating
fan_gender
fan_source
fan_metro_areas
fan_start_creation_date	Format YYYY-MM-DD
fan_end_creation_date	Format YYYY-MM-DD
idol_names
idol_relations
ticket_event_name
ticket_price_code
ticket_start_purchase_date
ticket_end_purchase_date
ticket_venue_name
ticket_venue_provinces
ticket_purchased_days
ticket_artist_name
ticket_start_event_date
ticket_end_event_date
ticket_seat_price_min
ticket_seat_price_max
ticket_seat_count_min
ticket_seat_count_max
ticket_sales_count_min
ticket_sales_count_max
ticket_is_negative
search_uid	If this parameter is supplied, we will continue returning records from previous search execution
limit	Maximum page size. Has to be less than a 1000
max_count	Maximum total number of records retrieved. Max value of 1,000,000. Default = 100,000

access_code
account_id
birth_date
city
country_code
creation_timestamp
creation_timestamp_iso
display_name
email
fan_id
fan_source
fields
first_name
gender
has_password
ip_address
is_confirmed
is_guest
is_optout
is_phone_confirmed
is_phone_subscribed
is_subscribed
last_campaign_name
last_name
last_page_tab_id
last_update_timestamp
last_update_timestamp_iso
latitude
longitude
media_uid	Fan profile picture media UID
metro_area
moderator_status
name
opted_in_business_ids	Business IDs of businesses that the fan is subscribed to. Will be an empty array unless include_business_opt_ins is included and set to true in the request.
phone
postal_code
profile_image_url	A link to the fans profile image (maximum 1024px x 1024px).
profile_image_preview_url	A link to the fans profile image preview (maximum 128px x 128px).
props
province
rating
tags

network *	Required.
identifier_value *	Required. URL encoded value of the identifier, e.g. email@gmail.com, %2B1234567890 (+1234567890). Exact match.

last_update_date	yyyy-mm-dd. Gets latest fans having last update date after this date.
min_time_key	The time key used to fetch the next page of updated fans. The format is '<unix_time>_<milliseconds>_<fan_id>'. Use the max_fan_time_key returned in the meta structure of previous request for fetching the next page.

start_date *	yyyy-mm-dd
end_date *	yyyy-mm-dd
point_name *
performance_uid	Optional. Filter point counts by a specific performance.

purchase_key *	A unique key for this purchase, recommended format {network}-{order_key}-{line_item_id}
network *	The network that the purchase originated from.
order_key *	An identifier for the order. Typically, an order will have multiple order items / purchases.
merchant_key *	An identifier for a specific merchant/seller which made the sale.
order_timestamp *	The timestamp when the purchase was made.
gross_sale_amount *	The gross sale amount made on this purchase.
net_sale_amount *	The net sale amount made on this purchase.
location_key	An identifier for specific location that the purchase was made.
customer_key	An identifier for the customer of this purchase.
email	The customer's email.
phone	The customer's phone.
country	The customer's country, can be a country code or country name.
province	The customer's province i.e. British Columbia
city	The customer's city i.e. Vancouver
product_key	An identifier for the product attached to this purchase.
product_name	A human-readable name for the product.
product_category	The category that the product falls under.

account_id
fan_id
network
identifier_value
creation_timestamp
creation_timestamp_iso

point_name
fan_id
fan_point_count	number of points based of filter
rank	rank of fan among all fans based on filter
display_name

purchase_key	A unique key for this purchase.
fan_id	The fan ID associated with this purchase.

account_id	The tradablebits account ID
network	The network that this purchase originates from.
purchase_key	A unique key for this purchase.
order_key	An identifier for an order, a single order may have multiple order items / purchases.
location_key	An identifier for a specific location.
merchant_key	An identifier for a specific merchant/seller.
customer_key	An identifier for the customer associated with this order.
fan_id	The fan ID associated with this purchase.
order_timestamp	The timestamp of the purchase in ISO format.
gross_sale_amount	The gross sale amount made on this purchase.
net_sale_amount	The net sale amount made on this purchase.
deduction_amount	The amount deducted on this purchase such as discounts or refunds.
product_key	An identifier for the product attached to this purchase.
product_name	A human-readable name for the product.
product_category	The category that this product falls under.
email	The customer email associated with this purchase_key.
phone	The customer phone associated with this purchase_key.
country_code	The customer's country code.
province	The customer's province.
city	The customer's city.

min_ticket_id	Window Specifier. Will return only tickets with ticket_id greater than given
max_ticket_id	Window Specifier. Will return only tickets with ticket_id less than given
min_purchase_date	Date filter option. Will return only tickets on or after a given date
max_purchase_date	Date filter option. Will return only tickets on or prior to a given date
min_last_update_date	Date filter option. Will return only tickets on or after a given date
max_last_update_date	Date filter option. Will return only tickets on or prior to a given data
email	Allows you to filter tickets to specific user/email address
limit	Max row count. Max. allowed value is 1000
data	Additional fields to include: supported value: fan
include_deleted	If set to true, return will include deleted tickets. Default = False

ticket_id	Unique Identifier for the ticket
ticket_key	Remote Tickey Key
account_id	Tradable Bits Acount ID
email	email on the ticket
customer_dsn	Identifies the tickets source
network	type of remote network to fetch ticket
event_key	Event Key in remote system
event_date	ISO date of the event
event_name	Event Name
purchase_timestamp	ISO Date
paid_amount	Total Paid Amount
order_amount	Full Order Amount
barcode	Wristband Barcode
lookup_id	Wristband Lookup ID
num_seats	Number of tickets/seats on the purchase
fan_id	Unique Fan Identifier
artist_name	Artist Name
price_code	Price Code or Level
venue_name	Name of Venue
city	City
province	Province or State
country_code	ISO country code
metro_area	DMA or CMA Area (Currently only for US/CA)
venue_province	Province or State of Venue
order_key	Identifier for the Order
ticket_category	Ticket Category
import_uid	Identifies the ticket import (if applicable)
postal_code	Postal Code / ZIP
customer_key	ID of customer in remote system
is_deleted	True if ticket deleted
ticket_type	Ticket Type
ticket_type_category	Category of Ticket Type
last_update_timestamp	Timestamp of last update in ISO 8601 format
original_paid_amount	Full paid ticket amount before discounts or fees
original_order_amount	Full order amount before discounts or fees
original_num_seats	Original number of seats
status	Ticket Status
fan	Fan reference
section_name	Ticket Section Name
row_name	Ticket Row Name
seat_num	Ticket Seat Number
plan_event_key	Plan Event Name

first_name *	String of the fans first name
last_name *	String of the fans last name
email *	String of the fans email address
purchase_timestamp *	YYYY-MM-DD HH:MI:SS in GMT timezone
paid_amount *	Numeric value for line item
num_seats *	Integer number of seats purchased
event_date *	ISO8601 Encoded String
event_name *	String of the event name
phone	String of the fans phone number
customer_key	Key of the customer in the remote system
ticket_key	Optional. Unique identifier for the line item (i.e. unique per price code and amount).
price_code	Optional. Price level or code of line item
is_subscribed	Boolean of the fan's email subscribe status
is_phone_subscribed	Boolean of the fans phone subscribe status
city	String of the fans city
province	String of the fans province
postal_code	String of the fans postal code
country_code	String of the fans country code
artist_name	String of the artist name
venue_name	String of the venue name
venue_province	String of the venue province
venue_country_code	String of the venue country code
event_key	String of the event key
network	String of the network
order_key	String of the order key
is_deleted	Boolean value
fan_source	Text identifier if fan is to be created

event_name	Must be exact name
event_key
event_date	Format YYYY-MM-DD
network
venue_name	Must be exact name
is_ticketless_only	Boolean, not allowed to be passed in combination with event_key, event_date, event_name or venue_name

event_uid	Unique identifier for the event
account_id
event_key
event_name
venue_name
artist_name
event_date
creation_timestamp
network
notes
label_name
event_type
customer_dsn
event_price
performance_uid
performance_name
is_edited
is_excluded
apply_historical
campaign_event_key
is_placeholder
short_event_name
creation_timestamp_iso

action	create / update / delete, defaults to create
event_uid	Unique identifier for the event, REQUIRED for update/delete
event_name *	Must be exact name
event_key *
event_date *	Format YYYY-MM-DD
network *
venue_name
artist_name
notes
label_name
event_type

max_purchase_date *	Format YYYY-MM-DD
min_purchase_date *	Format YYYY-MM-DD
event_name	Must be exact name.
event_key
event_date	Format YYYY-MM-DD.
venue_name	Must be exact name
artist_name
event_specific	Format 'true' or 'false'. Determines whether new/returning stats are by date only or by event as well. Default = False

returning_fans_count
new_fans_count
sales_count
seats_count
revenue

account_id	Tradable Bits Account ID
registration_key	Unique Identifier for the registration
order_key	Remote Ticket Key
event_name
event_date	ISO date of the event
event_key
fan_id
registration_timestamp	Timestamp of registration. Unix Time
registration_timestamp_iso	Timestamp of registration. ISO 8601 format
email	email on the ticket
venue_name
barcode
lookup_id
ticket_key
network
first_name
last_name
phone
address
city
country_code
province
postal_code
is_minor
birth_date
is_preferred
creation_timestamp	Timestamp of import. Unix Time
creation_timestamp_iso	Timestamp of import. ISO 8601 format
activity_id
is_subscribed
is_phone_subscribed
card_stored	If there was a cashless payment method saved as part of registration
performance_uid	Performance UUID of the ticket event associated with the registration

scan_group_name *	String. Identifier for different groups of scans. One of scan_group_name or scan_group_name_prefix is required.
scan_group_name_prefix	String. Perform prefix matching on scan_group_name. i.e. scan_group_name_prefix=abc will do a case-insensitive prefix search and return all rows that start with 'abc', 'ABC', etc. One of scan_group_name or scan_group_name_prefix is required.
start_date *	Scan creation start_date, scans between start_date and end_date will be fetched.
end_date *	Scan creation end_date, scans between start_date and end_date will be fetched
network *	The ticketing network.
next_scan_key	Used for pagination, each response will contain a 'next_scan_key' value which is to be supplied in the subsequent request in order to page through all records in the response. It does not need to be supplied on the first request to this endpoint.
venue_name	Venue name for the event.
event_date	Date of the event.

scan_key	An identifier associated with this scan
account_id	TradableBits account ID
network	Network associated with this scan
fan_id	Fan ID associated with this scan
event_key	The event key linked to this scan
is_success	Boolean field, represents whether the scan was successful
access_mode	The type of scan i.e. IN, OUT
scan_group_name	The group_set_name / scan_group_name for this scan.
site_name	Site name associated with this scan.
fgt_site_id	The integer ID for the site.
zone_name
scan_timestamp	The time that scan occurred
registration_key	The registration key.
order_key	The order key of the associated ticket.
ticket_key	The ticket key of the associated ticket.
pii_source	Can be one of: 'ticket' or 'registration'
event_name	The name of the event linked to the registration
event_date	The date of the event linked to the registration.
venue_name	Venue name linked to the registration
email
first_name
last_name
phone
country_code
province
postal_code
registration_timestamp	Timestamp when registration occurred
barcode	Wristband barcode associated with this scan/registration.

first_name	Max length 255 characters
last_name	Max length 255 characters
name	Max length 255 characters. If name is provided, the first and last name arguments will not be used.
email	Either Email or Phone is required
password
display_name	Max length is 32 characters. Longer names will be cut to this length. Profanity will be filtered
gender	Must be male, female, diverse, other, or empty.
is_subscribed	true/false/on/off
is_phone_subscribed
is_confirmed
is_phone_confirmed
phone	Either Email or Phone is required
birth_date
ip_address
latitude
longitude
business_<business_id>	Send business_<business_id> as the field and true/false/on/off as the value. True indicates a fan is opted in to the business, false will opt a fan out of the business.
tag_<tag_name>	Send tag_<tag_name> as a field with true/false/on/off as the value. If true, then the tag will be added to the fan, else the tag will be removed from the fan.
field_<crm_field_key>	Send field_<crm_field_key> as a field with some value i.e. field_my_key=helloworld. This will set the value of a custom field named 'my_key' to 'helloworld' on the fan.
fan_source	Text identifier if fan is to be created
is_optout
idol_names	Array of idol names to associate as fan idols

fan_id *	The fan_id whose country code should be used for phone validation.
identifiers *	The list must contain valid emails and/or phone numbers. Phone numbers from countries that differ from the fan's profile country must include a valid country prefix (e.g., +1, +52). If a prefix is not provided, the fan's profile country will be used for validation.
network	Only return fans who have an identifier associated with this network. To get a list of valid networks see /api/v1/networks

results	A list of successful lookup results, each item is an object with the original identifier and the matched fan record.
errors	A list of failed lookup results, each item is an object with the original identifier and the reason it failed.

network	Optional.
identifier_value	Optional. Search by the value of the identifier, e.g. email@gmail.com, +1234567890 (exact match).

fan_point_uid
fan_id
point_uid
point_name
point_count
point_source
creation_timestamp	Creation timestamp in ISO8601 format