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.

Front End

API

Integrations

Tradable Bits Server API

Most of CRM Data can be accessed with our HTTP based API. Calls operate using JSON data format and can be called with appropriate API Key. System recognises two form of keys: Public and Secret API Keys. Public is meant to be shared and used in insecure environment and Secret key is reserved for server-to-server communications and must be kept private. You can manage key under profile section once you log into Tradable Bits.

This Call Requires api_secret as 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 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

API Console

API Access allows you to query Stream and user data using RESTful API, as well as register for push notification from our CRM system. API Reference is broken into sections by topic: Facebook Apps (Campaigns) Data, Stream Data, CRM Data.

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://tradablebits.com/api/v1/

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

API KEY

API Secret

Additional Arguments

Arg 1

Val 1

Arg 2

Val 2

Arg 3

Val 3

Arg 4

Val 4

Results

Generated URL

Crm Calls

GET /v1/crm/activity_stats

Description

Aggregate Call to obtain counters based on the custom values in fan activities

Input Parameters

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

Result

Array of Counters

Resulting Structure

account_id
campaign_title
property_name
counter

GET /v1/crm/campaigns

Description

Get a list of Campaigns on the account.

Input Parameters

q	Text based filter to specific campaigns
limit	Optional parameter to specify max row count. Max. allowed value is 200

Result

Array of structures

Resulting Structure

account_id
campaign_type
title
page_tab_id
stream_key
app_type
is_active
creation_timestamp
winner_fan_id

GET /v1/crm/activities

Description

Download incremental list of activities for the account.Paging is implemented with help of usage of max_activity_id and mix_activity_id parameters. In the first call, system will include in meta information about given IDs. Now, by supplying min_activity_id you can fetch next batch of records.

Input Parameters

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 200
crm_campaign_id	Optional Filter to participants of specific campaign

Result

Structure: {'meta': { 'order':'desc/asc','min_activity_id':xxx,'max_activity_id':xxx},'data':[] }. Data is array with following elements

Resulting Structure

activity_id	Unique Identifier for the activity
account_id	Tradable Bits Account ID
fan_id	Unique Identifier for the fan record
creation_date	ISO Date of activity
campaign_title	Title of the campaign
campaign_type	Type of campaign (contest/login/etc)
app_type	For contests - type of contest
page_tab_id	Contest ID reference (set for contests only)
is_subscribed	OptIn flag on this activity
creation_timestamp	ISO timestamp of activity
crm_campaign_id	Campaign ID reference
stream_key	If activity is tied to stream - reference for stream
ip_address	IP Address
user_key	Facebook/Spotify/etc User Key
name	Full Name
email	Email
details	JSON structure of campaign details (varies by campaign)
fan	Fan Structure as per documentation
networks	List of connected networks
idol_names	List of connected Idols

GET /v1/crm/fans

Description

Search for Fan records using CRM Search interface

Input Parameters

name
crm_active_days
crm_inactive_days
crm_start_active_date
crm_end_active_date
fan_youngest_age
fan_oldest_age
fan_tags
fan_networks
fan_is_subscribed
fan_is_optout
fan_location
fan_rating
fan_gender
fan_metro_areas
idol_names
idol_affinity_score
idol_relations
ticket_event_name
ticket_price_code
ticket_start_purchase_date
ticket_end_purchase_date
ticket_venue_name
ticket_purchased_days
ticket_artist_name
ticket_start_event_date
ticket_end_event_date
query_line
ticket_seat_price_min
ticket_seat_price_max
ticket_seat_count_min
ticket_seat_count_max

Result

Array with Meta structure as part of result

Resulting Structure

fan_id
account_id
name
first_name
last_name
email
province
latitude
longitude
login_name
creation_timestamp
ip_address
country_code
city
tb_access_code
is_subscribed
rating
phone
birth_date
metro_area
postal_code
fields
image_url
gender
tags
reset_uid

GET /v1/crm/tickets

Description

Download incremental list of tickets for the account.Paging is implemented with help of usage of max_ticket_id and min_ticket_id parameters. In the first call, system will include in meta information about given IDs. Now, by supplying min_ticket_id you can fetch next batch of records.

Input Parameters

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 a given date
limit	Optional parameter to specify max row count. Max. allowed value is 3000
data	Additional fields to include: supported value: fan

Result

Structure: {'meta': { 'order':'desc/asc','min_ticket_id':xxx,'max_ticket_id':xxx},'data':[] }. Data is array with following elements

Resulting Structure

ticket_id	Unique Identifier for the ticket
ticket_key	Remote Tickey Key
account_id	Tradable Bits Acount ID
email	email on the ticket
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
num_seats	Number of tickets/seats on the purchase
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)
postal_code	Postal Code / ZIP
customer_key	ID of customer in remote system

POST /v1/crm/tickets

Description

Create new ticket and Corresponding Fan Record

Input Parameters

first_name	Required.
last_name	Required.
phone
email	Required.
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).
purchase_timestamp	Required. YYYY-MM-DD HH:MI:SS in GMT timezone
paid_amount	Required. Numeric value for line item
num_seats	Required. Number of seats purchased
price_code	Optional. Price level or code of line item
phone
city
province
postal_code
country_code
event_date	Required. ISO8601 Encoded String
event_name	Required.
artist_name
venue_name
event_key

Result

Created Record. Data will be returned as it was loaded in the system. I.e. sanitized

Resulting Structure

event_date
event_key
artist_name
venue_name
event_name
ticket_id
ticket_key
price_code
purchase_timestamp
paid_amount
num_seats
first_name
last_name
email
phone
province
country_code
city
metro_area
postal_code
status	success or duplicate if ticket already exists

POST /v1/crm/fans

Description

Create new Fan Record

Input Parameters

first_name
last_name
email
password
login_name
is_subscribed	true/false/on/off
phone
birth_date
ip_address

Result

Created Record

Resulting Structure

fan_id
account_id
name
first_name
last_name
email
province
latitude
longitude
login_name
creation_timestamp
ip_address
country_code
city
tb_access_code
is_subscribed
rating
phone
birth_date
metro_area
postal_code
fields
image_url
gender
tags
reset_uid

GET /v1/crm/fans/<fan_id>

Description

Get Specific fan record via ID

Result

Following structure

Resulting Structure

fan_id
account_id
name
first_name
last_name
email
province
latitude
longitude
login_name
creation_timestamp
ip_address
country_code
city
tb_access_code
is_subscribed
rating
phone
birth_date
metro_area
postal_code
fields
image_url
gender
tags
reset_uid

POST /v1/crm/fans/<fan_id>

Description

Update Fan Record

Input Parameters

first_name
last_name
email
password
login_name
is_subscribed	true/false/on/off
phone
birth_date
ip_address

Result

Updated Record

Resulting Structure

fan_id
account_id
name
first_name
last_name
email
province
latitude
longitude
login_name
creation_timestamp
ip_address
country_code
city
tb_access_code
is_subscribed
rating
phone
birth_date
metro_area
postal_code
fields
image_url
gender
tags
reset_uid

DELETE /v1/crm/fans/<fan_id>

Description

Delete Record

Result

Boolean

POST /v1/crm/fans/<fan_id>/merge

Description

Merge fan Record with another fan. As part of that fan_id will not longer be valid

Input Parameters

target_fan_id	Destination Dan Record

Result

New Fan Record

Resulting Structure

fan_id
account_id
name
first_name
last_name
email
province
latitude
longitude
login_name
creation_timestamp
ip_address
country_code
city
tb_access_code
is_subscribed
rating
phone
birth_date
metro_area
postal_code
fields
image_url
gender
tags
reset_uid

GET /v1/crm/fans//<fan_id>/followings

Description

Get list of Fan interests

Result

Array of interest records up to 10 for each network

Resulting Structure

network
name
follower_count

GET /v1/crm/fans/<fan_id>/idols

Description

Fetch list of idols for a given Fan

Input Parameters

label_name	Limit Idols to a specific label

Result

Array of Idols

Resulting Structure

spotify_follower_count
spotify_uid
facebook_follower_count
description
account_id
idol_uid
idol_name
facebook_id
media_uid
image_url

POST /v1/crm/fans/<fan_id>/idols

Description

Add or remove idol association

Input Parameters

action	add/delete
idol_uid

Result

Array of current Fan Idols

Resulting Structure

spotify_follower_count
spotify_uid
facebook_follower_count
description
account_id
idol_uid
idol_name
facebook_id
media_uid
image_url

GET /v1/crm/fans/<fan_id>/activities

Description

Obtain a list of activities for a given Fan

Input Parameters

limit	Record Limit
campaign_title	Limit results to specific campaign

Result

Array of records

Resulting Structure

account_id
fan_id
creation_date
campaign_title
campaign_type
props

POST /v1/crm/fans/<fan_id>/activities

Description

Create new Activity Record for a given Fan

Input Parameters

campaign_title	Name of custom campaign
field_*	Additional meta data as per defined custom fields

Result

Array of latest activities

Resulting Structure

account_id
fan_id
creation_date
campaign_title
campaign_type
props

GET /v1/crm/fields

Description

Get array of defined custom fields on the account

Result

Resulting Structure

crm_field_key
account_id
field_type
creation_timestamp
field_options
is_mandatory
group_name
is_active

Streams Calls

GET /v1/streams

Description

Produce a list of currently available streams.

Result

Resulting Structure

stream_key
account_id
creation_timestamp
stream_name
props
virtual_domain
css_text
javascript_text
record_limit
trust_level
media_map
is_public

POST /v1/streams

Description

Create new Stream in the system

Input Parameters

action	create/delete
stream_key
stream_name

Result

Array of streams

Resulting Structure

stream_key
account_id
creation_timestamp
stream_name
props
virtual_domain
css_text
javascript_text
record_limit
trust_level
media_map
is_public

GET /v1/streams/<stream_key>/records

Description

Search for approved records in the stream

Input Parameters

networks
label_key
sku
is_graphic
is_pinned
min_time_key	Max and Min time keys is a way to page through results. As part of Result - system returns max_time_key/min_time_key in the data.
max_time_key	Max and Min time keys is a way to page through results. As part of Result - system returns max_time_key/min_time_key in the data.
q
start_latitude
end_latitude
start_longitude
end_longitude

Result

{meta:{min_time_key:xx, max_time_keey:xx, row_count:xxx },data:[] }

Resulting Structure

stream_key
feed_record_id
record_key
props
creation_timestamp
image_url
src_image_url
video_url
caption
network
record_url
latitude
longitude
links
link_url
link_name
author_id
author_user_key
author_screen_name
author_name
author_image_url
author_status

POST /v1/streams/<stream_key>/records

Description

Create new Stream Record

Input Parameters

name
email
image_url
caption
latitude
longitude
props_*	Ability to store any meta data as part of the record

Result

Newly Created Record

Resulting Structure

stream_key
feed_record_id
record_key
props
creation_timestamp
image_url
src_image_url
video_url
caption
network
record_url
latitude
longitude
links
link_url
link_name
author_id
author_user_key
author_screen_name
author_name
author_image_url
author_status

GET /v1/streams/<stream_key>/identified_authors

Description

Fetch a list of stored authors in the stream

Input Parameters

q	Query String

Result

Array of author records

Resulting Structure

stream_key
network
user_key
name
screen_name
creation_timestamp
last_update_timestamp
status
is_follower
post_count

GET /v1/streams/<stream_key>

Description

Get Summary Stats on the stream

Input Parameters

data	Comma separated list of sections: words, hashtags, labels
label_key	Label Filter
start_time	optional date filter (specified as unix time)
end_time	optional date filter (specified as unix time)

Result

Summary Structure Record

Resulting Structure

stream_key
stream_name
total_stored
total
approved_total
authors
reach
last_record_timestamp
words
hashtags
labels

POST /v1/streams/<stream_key>/identified_authors

Description

update or delete a identified author

Input Parameters

action	create/delete
screen_name
status
network
user_key

Result

Boolean Value

GET /v1/streams/<stream_key>/<record_key>

Description

Get individual record

Result

Record Data

Resulting Structure

stream_key
feed_record_id
record_key
props
creation_timestamp
image_url
src_image_url
video_url
caption
network
record_url
links
link_url
link_name
author_id
author_user_key
author_screen_name
author_name
author_image_url
author_status

GET /v1/streams/<stream_key>/<record_key>/broken

Description

Mark a given record as the one requiring verification (e.g. image url is not valid)

Result

Boolean Value

GET /v1/streams/<stream_key>/proxy

Description

Execute Stream Request for Remote content on the fly without going through main infrastructure

Input Parameters

network
source_name
source_type
source_value

Result

Array of records

Resulting Structure

stream_key
record_key
creation_timestamp
image_url
video_url
record_url
caption
props
hashtags
network
latitude
longitude
record_media_uid
author_user_key
author_image_url
author_name
author_screen_name

GET /v1/streams/<stream_key>/feeds

Description

Get list of Stream Feeds

Result

Array of records

Resulting Structure

action	create/delete
network
source_type
source_name
source_value
label_id
label_key

POST /v1/streams/<stream_key>/feeds

Description

Create or update a feed in the stream

Input Parameters

action	create/delete
network
source_type
source_name
source_value
label_key

Result

Array of Feeds

Resulting Structure

action	create/delete
network
source_type
source_name
source_value
label_id
label_key

GET /v1/streams/<stream_key>/access_tokens

Description

Fetch Existing Access Tokens Configured on the stream

Result

Array of access tokens

Resulting Structure

stream_key
network
user_name
user_key
creation_timestamp
expiration_timestamp
access_token
token_secret
request_counter

POST /v1/streams/<stream_key>/access_tokens

Description

Update or Create an access token on the stream

Input Parameters

network
access_token
token_secret
user_name
user_id

Result

Array of currently enabled networks

Resulting Structure

stream_key
network
user_name
user_key
creation_timestamp
expiration_timestamp
access_token
token_secret
request_counter

Sessions Calls

POST /v1/sessions/idol_fans

Description

This is integration call to enable third part apps to pass artist affinity information over to us for proper segmentation

Input Parameters

network	Connected network. Network value can drive other require arguments. Supported: facebook, spotify,email
access_token	Mandatory for Facebook/Spotify
email	Optional for Facebook/Spotify
first_name	Optional for Facebook/Spotify
last_name	Optional for Facebook/Spotify
idol_name	Reference to the artist name. Idol will be created if it doesn't exist yet
device_id	Hardware reference if mobile app is used
device_network	one of ios/android

Result

true if call is successful, error otherwise

POST /v1/sessions/connect

Description

This call allows to initialize new session and potentially create new fan Record in the system. It can be used for native and website integration and is essential for proper integration.

Input Parameters

network	Connected network. Network value can drive other require arguments. Most common values: facebook, spotify, register, connect, reset, email
access_token
ip_address
email
name
phone
password
access_secret
device_id
device_network

Result

New Session Object

Resulting Structure

session_uid
fan_id
account_id
props
expiration_timestamp

GET /v1/sessions/<session_uid>

Description

Get existing Session using ID

Result

Record

Resulting Structure

session_uid
fan_id
account_id
props
expiration_timestamp

GET /v1/sessions/<session_uid>/fan

Description

Fetch current Fan Record

Result

Following Structure

Resulting Structure

fan_id
account_id
name
first_name
last_name
email
province
latitude
longitude
login_name
creation_timestamp
ip_address
country_code
city
tb_access_code
is_subscribed
rating
phone
birth_date
metro_area
postal_code
fields
image_url
gender
tags
reset_uid

POST /v1/sessions/<session_uid>/fan

Description

Update Current Fan Record

Input Parameters

first_name
last_name
email
password
login_name
is_subscribed	true/false/on/off
phone
birth_date
ip_address

Result

Updated Record

Resulting Structure

fan_id
account_id
name
first_name
last_name
email
province
latitude
longitude
login_name
creation_timestamp
ip_address
country_code
city
tb_access_code
is_subscribed
rating
phone
birth_date
metro_area
postal_code
fields
image_url
gender
tags
reset_uid

GET /v1/sessions/<session_uid>/networks

Description

Get a list of connected networks for a given Fan Record

Result

Array of connected networks

Resulting Structure

fan_id
account_id
name
email
user_key
network
creation_timestamp
profile_url
follower_count
props
image_url

GET /v1/sessions/<session_uid>/activities

Description

Fetch current Fan Activities

Input Parameters

limit	max row count
campaign_title	Limit results to specific campaign

Result

Array of last activities

Resulting Structure

fan_id
campaign_title
campaign_type
creation_date
creation_timestamp
props

GET /v1/sessions/<session_uid>/followings

Description

Fetch current Fan Followed Interests

Result

Array of followings

Resulting Structure

network
name
follower_count

POST /v1/sessions/<session_uid>/activities

Description

Create Activity record to associate with current Fan

Input Parameters

campaign_title	Name of new Custom Campaign
field_*

Result

Array of last activities

Resulting Structure

fan_id
campaign_title
campaign_type
creation_date
creation_timestamp
props

GET /v1/sessions/<session_uid>/idols

Description

Fetch a list of connected idols

Input Parameters

label_name	Limit Idols to a specific label

Result

Array of following structures

Resulting Structure

spotify_follower_count
spotify_uid
facebook_follower_count
description
account_id
idol_uid
idol_name
facebook_id
media_uid
image_url

POST /v1/sessions/<session_uid>/idols

Description

Create or Delete association between current Fan and Idol

Input Parameters

action	One of: add, delete
idol_uid	UUID for a given idol

Result

Array of currently connected idols

Resulting Structure

spotify_follower_count
spotify_uid
facebook_follower_count
description
account_id
idol_uid
idol_name
facebook_id
media_uid
image_url

GET /v1/sessions/<session_uid>/fan_events

Description

Get a list of events for a session's Fan

Input Parameters

label_name	Limit Idols to a specific label

Result

Array of records as per following structure

Resulting Structure

fan_id
creation_timestamp
event_uid

POST /v1/sessions/<session_uid>/fan_events

Description

Create new association between event and fan or delete existing one

Input Parameters

action	one of: add or delete
event_uid	UUID for a valid event

Result

ID of event

Idols Calls

GET /v1/idols

Description

Search for an idols in the database

Input Parameters

idol_name	Search Expression for an idol
label_name	Limit Idols to a specific label

Result

Array of idol structures

Resulting Structure

spotify_follower_count
spotify_uid
facebook_follower_count
description
account_id
idol_uid
idol_name
facebook_id
media_uid
image_url

GET /v1/idols/<idol_uid>

Description

Obtain an idol for a given idol_uid

Result

A structure for a given idol as follows

Resulting Structure

spotify_follower_count
spotify_uid
facebook_follower_count
description
account_id
idol_uid
idol_name
facebook_id
media_uid
image_url

GET /v1/idols/<idol_uid>/rel_artists

Description

Obtain a list of artists related to a given Idol

Input Parameters

label_name	Optional argument to limit idols with a given label only

Result

Array of records as per following structure

Resulting Structure

idol_uid
idol_name
artist_name
facebook_id
image_url

GET /v1/idols/events

Description

Based on the search parameters return a list of Idol Events.

Input Parameters

idol_uid
venue_name
q
label_name
start_date
end_date

Result

Array of JSON records matching the search

Resulting Structure

event_uid
account_id
idol_uid
start_timestamp
end_timestamp
venue_name
city
province
country_code
event_url
ticket_url
label_name
idol_name
facebook_id
media_uid
image_url

GET /v1/idols/events/<event_uid>

Description

Get individual Scheduled Event given event_uid

Result

JSON structure with Event Details or null

Resulting Structure

event_uid
account_id
idol_uid
start_timestamp
end_timestamp
venue_name
city
province
country_code
event_url
ticket_url
label_name
idol_name
facebook_id
media_uid
image_url

tracker_id	Identifier for Tracker
account_id
creation_timestamp	UNIX timestamp for creation
tracker_name
tracker_group_name
target_url
virtual_domain
click_count
tracker_url

virtual_domain	Domain. Must be preconfigured and setup by Tradable Bits
target_url
tracker_name
tracker_group_name
network	spotify, instagram, facebook, google, twitter or custom

start_date	Optional date filter for stats
end_date	Optional date filter for stats

page_tab_id
name
total_entries
fan_count
view_count
unique_view_count
subscribers