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
Most of CRM Data can be accessed with our HTTP based API. Calls should be sent as application/x-www-form-urlencoded and will return JSON data. Authentication is handled using 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 whereas 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 key under profile section once you log into Tradable Bits.
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: Meta 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.
Crm Calls
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 |
Description
Get a list of Campaigns on the account.
Input Parameters
| q | Text based filter to specific campaigns |
Result
Array of structures
Resulting Structure
| account_id | |
| title | |
| page_tab_id | |
| stream_key | |
| app_type | |
| is_active | |
| creation_timestamp | |
| winner_fan_id |
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 |
| page_tab_id | Optional Filter to participants of specific campaign |
| activity_date | Optional Filter to participants for specific date |
| include_details | Include additional details: fan, idols, connections |
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 |
| 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 |
| page_tab_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 |
| 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 |
Description
Submit new Activity as well as Fan details for data integration
Input Parameters
| first_name | |
| last_name | |
| phone | |
| campaign_title | |
| province | |
| postal_code | |
| country_code | |
| is_subscribed | |
| is_phone_subscribed |
Result
Structure matching the input with validated fields
Description
Fetch a list of existing crm fan tags for the purposes of synchronization. Request is limited to 10000 records max in a single result set.
Input Parameters
| 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 |
Result
Array
Resulting Structure
| tag_name | |
| tag_id | |
| fan_id | |
| creation_timestamp | |
| first_name | |
| last_name | |
Description
Search for Fan records using CRM Search interface
Input Parameters
| name | Name or Email of the person in question |
| 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 | |
| fan_tag_relations | |
| fan_networks | |
| fan_is_subscribed | |
| fan_is_optout | |
| fan_is_phone_subscribed | |
| fan_postal_codes | |
| fan_provinces | |
| fan_rating | |
| fan_gender | |
| fan_metro_areas | |
| fan_start_creation_date | Format YYYY-MM-DD |
| fan_end_creation_date | Format YYYY-MM-DD |
| 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_venue_provinces | |
| 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 | |
| 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 |
Result
Array with Meta structure as part of result
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| login_name | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags | |
| opted_in_business_ids |
Description
Get the latest updated fans. The last_update_date parameter can be used to get fans which were updated after a particular date. The min_time_key can be used to fetch the next page of updated fans. Each page has a size limit of 1000.
Input Parameters
| last_update_date | Optional. yyyy-mm-dd. Gets latest fans having last update date after this date. |
| min_time_key | Optional. 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. |
Result
Structure: {'meta': { 'min_fan_time_key':'xxx', 'max_fan_time_key':xxx, 'count':xxx }, 'data':[] }. Data is array with following elements
Resulting Structure
| fan_id | |
| login_name | |
| first_name | |
| last_name | |
| latitude | |
| longitude | |
| city | |
| province | |
| country_code | |
| metro_area | |
| postal_code | |
| ip_address | |
| is_optout | |
| is_phone_subscribed | |
| gender | |
| rating | |
| birth_date | |
| phone | |
| is_phone_confirmed | |
| display_name | |
| fan_time_key | |
| creation_timestamp | |
| last_update_timestamp | |
| creation_timestamp_iso | ISO creation timestamp |
| last_update_timestamp_iso | ISO last update timestamp |
Description
Get a fan leaderboard based on provided filters
Input Parameters
| start_date | yyyy-mm-dd |
| end_date | yyyy-mm-dd |
| point_name |
Result
Array with Meta structure as part of result
Resulting Structure
| fan_id | |
| first_name | |
| last_name | |
| fan_point_count | number of points based of filter |
| rank | rank of fan among all fans based on filter |
Description
Initiate an event of the ticket change. This call is designed to be used as part of ticketing integration to cause a crawl. Crawl will be asynchronous in nature and done later
Input Parameters
| customer_dsn | Ticketing integration name. Provided by Tradable Bits support |
| network | Ticketing integration type. Provided by Tradable Bits support |
| order_key | Ticket Order Identifier |
Result
Boolean: true
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 |
| Optionally this parameter allows you to filter tickets to specific user/email address | |
| 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 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 |
Description
Create new ticket and Corresponding Fan Record
Input Parameters
| first_name | Required. |
| last_name | Required. |
| phone | |
| 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 | |
| network | |
| order_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 | |
| network | |
| fan_id | |
| first_name | |
| last_name | |
| phone | |
| province | |
| country_code | |
| city | |
| metro_area | |
| postal_code | |
| status | success or duplicate if ticket already exists |
| order_key |
Description
Query Wristband/RFID registrations from the database
Input Parameters
| start_date | Date filter option. Will return only tickets on or after a given date |
| end_date | Date filter option. Will return only tickets on or prior a given date |
| Optionally this parameter allows you to filter tickets to specific user/email address | |
| limit | Optional parameter to specify max row count. If omitted, will be set to 1000 |
Result
Structure: {'meta': { 'count':xxx },'data':[] }. Data is array with following elements
Resulting Structure
| registration_key | Unique Identifier for the registration |
| order_key | Remote Ticket Key |
| account_id | Tradable Bits Account ID |
| email on the ticket | |
| event_date | ISO date of the event |
| registration_timestamp | Timestamp of registration. Unix Time |
| creation_timestamp | Timestamp of import. Unix Time |
| price_code | Price Code or Level |
Description
Create new registration and Corresponding Fan Record
Input Parameters
| first_name | Required. |
| last_name | Required. |
| phone | |
| Required. | |
| registration_key | Unique identifier for the line item |
| registration_timestamp | Required. YYYY-MM-DD HH:MI:SS in GMT timezone |
| order_key | |
| price_code | Optional. Price level or code of line item |
| event_date | Optional. Date of the Event. ISO Date |
Result
Created Record. Data will be returned as it was loaded in the system. I.e. sanitized
Resulting Structure
| registration_key | Unique Identifier for the registration |
| order_key | Remote Ticket Key |
| account_id | Tradable Bits Account ID |
| email on the ticket | |
| event_date | ISO date of the event |
| registration_timestamp | Timestamp of registration. Unix Time |
| creation_timestamp | Timestamp of import. Unix Time |
| price_code | Price Code or Level |
Description
Create new Fan Record
Input Parameters
| first_name | |
| last_name | |
| password | |
| login_name | |
| is_subscribed | true/false/on/off |
| is_phone_subscribed | |
| phone | |
| birth_date | |
| ip_address | |
| latitude | |
| longitude |
Result
Created Record
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| login_name | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
Description
Get Specific fan record via ID
Result
Following structure
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| login_name | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
Description
Update Fan Record
Input Parameters
| first_name | |
| last_name | |
| password | |
| login_name | |
| is_subscribed | true/false/on/off |
| is_phone_subscribed | |
| phone | |
| birth_date | |
| ip_address | |
| country_code | |
| province | country_code is required |
| city | country_code is required |
| postal_code | country_code is required |
Result
Updated Record
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| login_name | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
Description
Delete Record
Result
Boolean
Description
Get Fan Networks
Result
JSON
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| user_key | |
| network | |
| creation_timestamp | |
| last_update_timestamp | |
| props | |
| access_token | |
| access_secret |
Description
Create/Update/Delete Fan Networks
Input Parameters
| action | create/update/delete |
| name | |
| user_key | Required |
| network | Required. Must be "custom" for create and update |
| creation_timestamp | |
| last_update_timestamp | |
| props | |
| access_token | |
| access_secret |
Result
JSON
Description
Get Fan points
Result
Following structure
Resulting Structure
| fan_id | |
| point_uid | |
| point_name | |
| point_count |
Description
award a fan points
Input Parameters
| point_name | |
| point_count |
Result
[]
Description
Merge fan record with another fan. As a result, the source fan_id will no longer be valid.
Input Parameters
| target_fan_id | Destination Fan Record |
Result
New Fan Record
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| login_name | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
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 |
Description
Add or remove idol association
Input Parameters
| action | add/delete |
| idol_uid | |
| idol_name | Name for a given (as alternative to UUID) |
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 |
Description
Obtain a list of known registrations for the fan. Registration is tied to RFID bracelet or some form of ticket
Input Parameters
| limit | Record Limit |
Result
Array of records
Resulting Structure
| registration_timestamp | |
| account_id | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| fan_id | |
| registration_timestamp | |
| creation_timestamp |
Description
Create new Registration Record for a given Fan
Input Parameters
| registration_timestamp | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| registration_timestamp |
Result
Array of latest registrations
Resulting Structure
| registration_timestamp | |
| account_id | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| fan_id | |
| registration_timestamp | |
| creation_timestamp |
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 | |
| props |
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 | |
| props |
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_active | |
| is_global |
Description
Get array of monitored ip addresses on the account
Result
Resulting Structure
| page_tab_id | |
| ip_address | |
| is_blocked | True if the address is banned, false if it is whitelisted |
| creation_timestamp |
Description
Get array of monitored ip addresses on the account
Input Parameters
| action | insert or delete |
| ip_address | |
| is_blocked | True to ban users at this ip address, false to whitelist them |
| page_tab_id | Optional for insert action. If included, will ban or whitelist the given address for only this page tab |
Result
Resulting Structure
| page_tab_id | |
| ip_address | |
| is_blocked | True if the address is banned, false if it is whitelisted |
| creation_timestamp |
Streams Calls
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 |
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 |
Description
Search for approved records in the stream
Input Parameters
| networks | |
| label_key | |
| sku | |
| is_graphic | |
| 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 |
Description
Create new Stream Record
Input Parameters
| name | |
| 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 |
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 |
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 |
Description
Approve individual Record or Label it accordingly
Input Parameters
| action | approve/remove/label/unlabel |
| label_key |
Result
Update 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 |
Description
Mark a given record as the one requiring verification (e.g. image url is not valid)
Result
Boolean Value
Sessions Calls
Description
This endpoint enables third party apps to pass Wifi Authentication Information
Input Parameters
| network | Connected network. Network value can drive other require arguments. Supported: facebook, spotify, email |
| access_token | Mandatory for Facebook/Spotify |
| Optional for Facebook/Spotify | |
| first_name | Optional for Facebook/Spotify |
| last_name | Optional for Facebook/Spotify |
| activity_name | Reference to the Activity or Event name. |
| device_id | Hardware reference if mobile app is used |
| device_network | one of ios/android |
Result
true if call is successful, error otherwise
Description
This endpoint enables third party apps to submit artist affinity information for segmentation
Input Parameters
| network | Connected network. Network value can drive other require arguments. Supported: facebook, spotify,email |
| access_token | Mandatory for Facebook/Spotify |
| 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
Description
This endpoint enables third-party apps to push email signup or some other form of activity into our CRM.
Input Parameters
| phone | |
| first_name | |
| last_name | |
| birth_date | String in the form 'YYYY-MM-DD' |
| city | City. country_code is required if included. |
| country_code | 2 letter country code or full country name |
| postal_code | Postal Code in a given country. country_code is required if included |
| province | Province name. country_code is required if included |
| ip_address | Optional Field. Will take REMOTE_ADDR if omitted |
| device_id | Hardware reference if mobile app is used |
| device_network | one of ios/android |
| field_xxxx | Custom field value for configured custom fields |
| is_unique_activity | true/false - enforce unique participation in the campaign |
| campaign_name | Campaign Connection, if call is meant to be associated with campaign |
| page_tab_id | Campaign Connection, if call is meant to be associated with campaign. This field should be used instead of the campaign_name field if possible and will supersede it if filled |
| tag_name | CRM Tag to apply to the user. Can be specified multiple times in the payload |
| tag_names | As alternative to tag_name, tags can be supplied as comma separated list |
| business_id | Opt-in to a specific business, if applicable |
| idol_name | Idol to associate with the user |
Result
Structure as below
Resulting Structure
| fan_id | Fan ID of the records |
| activity_id | Activity ID if it was created properly |
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. An empty string as network value is used to create a guest session without a fan record. Most common values: facebook, spotify, yinzcam, twitter, register, email, verify_sms, verify_email, submit_verification_code |
| business_id | Required |
| page_tab_id | |
| access_token | |
| ip_address | |
| name | |
| phone | |
| password | |
| access_secret | |
| is_accepted | Flag to confirm terms acceptance. Required if terms_required is returned |
| device_id | |
| device_network |
Result
New Session Object (or structure to represent a step in login flow
Resulting Structure
| session_uid | |
| fan_id | |
| account_id | |
| props | |
| expiration_timestamp |
Description
Get existing Session using ID
Result
Record
Resulting Structure
| session_uid | |
| fan_id | |
| account_id | |
| props | |
| expiration_timestamp |
Description
Fetch current Fan Record
Result
Following Structure
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| login_name | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| image_url | |
| gender | |
| tags |
Description
Update Current Fan Record
Input Parameters
| first_name | |
| last_name | |
| password | |
| login_name | |
| is_subscribed | true/false/on/off |
| is_phone_subscribed | true/false/on/off |
| phone | |
| birth_date | |
| ip_address | |
| props_* | update props |
| field_* | update fields |
| tag_* | update tags |
Result
Updated Record
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| login_name | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| image_url | |
| gender | |
| tags |
Description
Get a list of connected networks for a given Fan Record
Result
Array of connected networks
Resulting Structure
| fan_id | |
| account_id | |
| name | |
| user_key | |
| network | |
| creation_timestamp | |
| last_update_timestamp | |
| profile_url | |
| follower_count | |
| props | |
| image_url | |
| access_token | |
| access_secret |
Description
Create/update/delete connected networks for a given Fan Record
Input Parameters
| action | create/update/delete |
| name | |
| user_key | Required |
| network | Required. Must be "custom" for create and update |
| creation_timestamp | |
| last_update_timestamp | |
| profile_url | |
| follower_count | |
| props | |
| image_url | |
| access_token | |
| access_secret |
Result
JSON
Description
Obtain a list of known tickets for the fan.
Input Parameters
| limit | Record Limit |
Result
Array of records
Resulting Structure
| ticket_id | |
| account_id | |
| event_name | |
| artist_name | |
| venue_name | |
| price_code | |
| event_date | |
| paid_amount | |
| num_seats | |
| purchase_timestamp | |
| creation_timestamp |
Description
Update one of tickets on the account
Input Parameters
| action | Currently only transfer is supported |
| ticket_id | |
| first_name | |
| last_name |
Result
Array of latest tickets
Resulting Structure
| ticket_id | |
| account_id | |
| event_name | |
| artist_name | |
| venue_name | |
| price_code | |
| event_date | |
| paid_amount | |
| num_seats | |
| purchase_timestamp | |
| creation_timestamp |
Description
Obtain a list of known registrations for the fan. Registration is tied to RFID bracelet or some form of ticket
Input Parameters
| limit | Record Limit |
Result
Array of records
Resulting Structure
| registration_timestamp | |
| account_id | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| fan_id | |
| registration_timestamp | |
| creation_timestamp |
Description
Create new Registration Record for a given Fan
Input Parameters
| registration_timestamp | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| registration_timestamp |
Result
Array of latest registrations
Resulting Structure
| registration_timestamp | |
| account_id | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| fan_id | |
| registration_timestamp | |
| creation_timestamp |
Description
Get Fan points
Result
Following structure
Resulting Structure
| fan_id | |
| point_uid | |
| point_name | |
| point_count |
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 | |
| creation_date | |
| creation_timestamp | |
| props |
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 | |
| creation_date | |
| creation_timestamp | |
| props |
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 |
Description
Create or Delete association between current Fan and Idol
Input Parameters
| action | One of: add, delete |
| idol_uid | UUID for a given idol |
| idol_name | Name for a given (as alternative to UUID) |
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 |
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 |
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
Description
Media Stream integration: retrieve a new unique access token for a given session UID.
Input Parameters
| id | ID of the video |
Result
JSON structure with access_token as a field
Idols Calls
Description
Create new idol in the database
Input Parameters
| idol_name | Name of the new idol |
| spotify_uid | Optional Spotify UID if it's available |
Result
idol structure
Resulting Structure
| spotify_follower_count | |
| spotify_uid | |
| facebook_follower_count | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| facebook_id | |
| media_uid | |
| image_url |
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 |
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 |
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 |
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 |
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 |
Reports Calls
Description
Get all shared reports asociated with the current account.
Result
Array of JSON objects as per structure below
Resulting Structure
| report_uid | Identifier of the report |
| report_name | Name of the report |
| report_type | Type of the report. One of 'adwords_adaccount', 'app', 'bot', 'crm', 'fb_adaccount', 'idol', 'sms', 'stream', 'ticket', 'tracker' |
| start_date | Start date for the report's data |
| end_date | End date for the report's data |
| last_access_timestamp | Timestamp for when the report was last accessed |
Description
Get data for a shared report.
Result
Structure: {'<report_type>': {}}. Corresponding object to the report's type is the data for the report, whose structure depends on the report's type. Below is structure for 'fb_adaccount' stats report.
Resulting Structure
| spend | Total spending |
| conversion | Total sales value attributable to ads |
| offline_conversion | Sales value attributable to offline conversion |
| conversion_count | Number of sales |
| impressions | Total number of impressions |
| reach | Total number of unique people reached |
| frequency | Average frequency per unique person |
| cpm | Cost-per-thousand |
| cpa | Cost-per-action |
| roi | Return on investment rate |
| clicks | Total number of clicks |
| ctr | Clickthrough rate |
| cpc | Cost-per-click |
Ads Calls
Description
Create a new budget line for an ad project
Input Parameters
| name | Name of the budget line |
| budget_amount | Monetary amount of budget line |
| notes | Budget line notes |
Result
JSON object as per structure below
Resulting Structure
| project_line_uid | |
| project_uid | |
| creation_timestamp | |
| budget_amount | |
| ip_address | |
| name | |
| notes | |
| campaign_names | |
| currency | |
| creation_timestamp_iso |
Misc Calls
Description
Get a list of recently created Trackers (last 500 trackers)
Result
Array of JSON objects as per structure below
Resulting Structure
| 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 |
Description
Get individual tracker as specified by ID
Result
JSON structure
Resulting Structure
| 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 |
Description
Create New Tracker for measurement of redirect performance. This call allows to automate creation of Tradable Bits Trackers
Input Parameters
| 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 |
Result
Upon Success, call will return a structure for created tracker
Resulting Structure
| 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 |
Description
This call allows to store and retrieve back json data structure. Primary use for this call is some form of simple voting, which doesn't require any cheater or inappropriate use detection
Input Parameters
| props | Data structure to save |
Result
The value currently stored under this prop_name
Description
Get regional information from an IP address
Input Parameters
| ip_address | IPv4 or IPv6 address. otherwise caller ip will be used |
Result
Regional information associated with that IP address
Resulting Structure
| city | |
| region_name | |
| latitude | |
| longitude | |
| country_name | |
| postal_code |
Description
Get regional information from an IP address
Input Parameters
| phone | Phone number. The more complete the number the better. |
| country_code | lower case two letter ISO code of the country |
Result
Error message or text value of validated phone
Description
Lookup product on Shopify
Input Parameters
| query |
Result
A list of matching shopify products
Description
Part of the integration with Yinzcam for push tokens sync
Input Parameters
| user_key | |
| push_token | |
| device_network |
Result
Boolean Value of True
Description
Fetch ad stats for the account
Result
A list of structures with the following fields
Resulting Structure
| network | Ad platform, e.g. facebook, twitter |
| spend | |
| impressions | |
| clicks |
Apps Calls
Description
Get a list of campaigns on the account
Input Parameters
| app_type | Limit Results to specific type |
| is_scheduled | Whether or not campaign is included into scheduler |
| business_id | Limit request to specific business |
Result
An array of structures with following fields
Resulting Structure
| page_tab_id | |
| name | |
| app_type | |
| creation_timestamp | |
| live_status | |
| business_id | |
| is_scheduled | |
| is_active | |
| media_map | |
| timezone | |
| props | |
| locale_props | |
| style_props | |
| links_map |
Description
Get a list of businesses on the account
Result
An array of structures with following fields
Resulting Structure
| legal_rules | |
| legal_terms | |
| legal_privacy | |
| business_id | |
| business_name | |
| media_map | |
| scheduler_props | |
| locale_props | |
| style_props |
Description
Get a specific Business record given ID
Result
structure with following fields
Resulting Structure
| legal_rules | |
| legal_terms | |
| legal_privacy | |
| business_id | |
| business_name | |
| media_map | |
| scheduler_props | |
| locale_props | |
| style_props |
Description
Obtain statistical data for a specific bundle campaign
Input Parameters
| start_date | Optional date filter for stats |
| end_date | Optional date filter for stats |
Result
A structure with following keys
Resulting Structure
| summary | A dictionary of summary data for all campaigns included in the bundle with keys [start_date, end_date, total_views, total_shares, total_entries, total_optins] |
| bundles | A list of dictionaries representing all campaigns included in the bundle with keys [name, page_tab_id, views, shares, entries, opt_ins, max_views |
Description
Obtain statistical data on executed campaign
Input Parameters
| start_date | Optional date filter for stats |
| end_date | Optional date filter for stats |
Result
A structure with following fields
Resulting Structure
| page_tab_id | |
| name | |
| total_entries | |
| fan_count | |
| view_count | |
| unique_view_count | |
| subscribers | Number of unique fans who subscribe to at least one of phone or email |
| phone_subscribers | Number of phone subscribers |
| email_subscribers | Number of email subscribers |
Description
Fetch detailed stats for a campaign
Input Parameters
| target | One of leaderboard, fan_points, quiz_results, clicker_results, chat_history, overlay_timeline, feed_switching, websocket_connections,websocket_raw_connections,wager_points |
| start_timestamp | Optional date filter |
| end_timestamp | Optional date filter |
| tab_item_id | Optional filter to specific tab items |
Result
Array of objects depending on your requested target
Description
Get all props for a specific page tab
Result
A structure of campaign props with configured attributes
Description
Fetch configuration of existing campaign for custom visual or other purposes
Input Parameters
| include_details | Boolean value to include details like quiz questions/tab items/etc. |
Result
A structure of campaign with configured attributes
Description
Fetch total fan points for a campaign
Input Parameters
| start_timestamp | Optional date filter |
| end_timestamp | Optional date filter |
Result
A structure with following fields
Resulting Structure
| total_points |
Description
Fetch entries for a wager campaign
Input Parameters
| q | Query string |
| start_date | Optional date filter |
| end_date | Optional date filter |
Result
An array of Structures with following fields
Resulting Structure
| tab_item_id | |
| page_tab_id | |
| creation_date | |
| title | |
| subtitle | |
| description | |
| item_url | |
| tag_id | |
| tag_name | |
| position | |
| active_date | |
| props | |
| inventory_count | |
| item_count | |
| item_group_name | |
| activation_timestamp | |
| price | |
| media_uid | |
| items_purchased | |
| latitude | |
| longitude | |
| media_map | |
| wagers |
Description
Fetch fan points for a campaign without any PII
Input Parameters
| start_timestamp | Optional date filter |
| end_timestamp | Optional date filter |
Result
A structure with following fields
Resulting Structure
| fan_id | |
| point_count | |
| creation_timestamp |
Description
Fetch fan activities for a campaign without any PII
Result
A structure with following fields
Resulting Structure
| fan_id | |
| activity_id | |
| creation_timestamp |
Fanxp Calls
Description
Verify FanXP campaign status and obtain required element to render it.
Input Parameters
| session_uid | A valid session identifier for logged in user |
Result
A Structure with following fields
Resulting Structure
| page_tab_id | |
| live_status | |
| pinned_overlays | |
| overlays | |
| shopify_products | |
| props | |
| style_props | |
| privacy | |
| terms | |
| rules | |
| links_map |
Description
Check and return if ip address is registered in Chat moderation
Input Parameters
| ip_address | Optional ip address. REMOTE_ADDR is used otherwise |
Result
A Structure with following fields
Resulting Structure
| is_blocked | |
| ip_address |
Description
Fetch last 20 messages for a given channel on behalf of a user
Input Parameters
| session_uid | A valid session identifier for logged in user |
| room_name | Optional link to specific room for private messaging |
Result
An array of Structures with following fields
Resulting Structure
| chat_message_uid | |
| creation_timestamp | |
| room_name | |
| display_name | |
| message | |
| fan_id | |
| moderator_status |
Description
Fetch friends on behalf of a user
Input Parameters
| session_uid | A valid session identifier for logged in user |
Result
An array of Structures with following fields
Resulting Structure
| fan_id | |
| is_approved | null for a requested friend, true for an accepted friend and false for a declined friend. |
| creation_timestamp | |
| last_update_timestamp | |
| display_name | |
| is_online |
Description
Update friends on behalf of a user
Input Parameters
| session_uid | A valid session identifier for logged in user |
| fan_id | fan_id of the friend to modify (not the session fan) |
| action | remove is the only currently supported action |
Result
A Dictionary with the following fields
Resulting Structure
| status |
Description
Fetch friend requests on behalf of a user
Input Parameters
| session_uid | A valid session identifier for logged in user |
Result
An dictionary of incoming and outgoing requests containing arrays of Structures with following fields
Resulting Structure
| fan_id | |
| is_approved | |
| creation_timestamp | |
| last_update_timestamp | |
| display_name |
Description
Update friend requests on behalf of a user
Input Parameters
| session_uid | A valid session identifier for logged in user |
| fan_id | fan_id of the friend to modify (not the session fan) |
| action | one of [accept, decline, cancel, request] |
Result
A Dictionary with the following fields
Resulting Structure
| status |
Description
Fetch detailed chat history
Input Parameters
| limit | Max # of records to return |
| q | Query string |
| min_timestamp | Only return messages sent after this timestamp, used for pagination |
| max_timestamp | Only return messages sent before this timestamp, used for pagination |
Result
A Dictionary with the following fields
Resulting Structure
| messages | An array of chat messages. See chat_messages endpoint for structure |
| min_timestamp | Earliest timestamp returned. Send this as max_timestamp in a future call to page backwards |
| max_timestamp | Latest timestamp returned. Send this as min_timestamp in a future call to page forwards |
Description
Push new clicker data.
Input Parameters
| session_uid | A valid session identifier for logged in user |
| instance_uid | Clicker instance reference |
| click_count | Click count |
Result
True
Description
Push new fan points data.
Input Parameters
| session_uid | A valid session identifier for logged in user |
| point_count | Value of points |
| point_name | Optional Point Name |
Result
True or False
Description
Report a chat message
Input Parameters
| session_uid | A valid session identifier for logged in user |
| chat_message_uid | ID of the message to report |
Result
Confirmation of the save
Description
Answer a question
Input Parameters
| session_uid | A valid session identifier for logged in user |
| quiz_question_id | Identifier for the question as per earlier message |
| answer_idx | Index of the answer as per websocket message |
Result
Confirmation of the save
Description
Get the status of result
Input Parameters
| session_uid | A valid session identifier for logged in user |
| quiz_question_id | Identifier for the question as per earlier message |
Result
Result Line
Description
Get a Public Leaderboard
Input Parameters
| session_uid | A valid session identifier for logged in user |
| friends_only | Only return leaderboard info for friends of the logged in user |
Result
An array of following rows
Resulting Structure
| fan_id | |
| display_name | |
| correct_answer_count | |
| points | |
| clicker_points |
Description
Obtain current values for team stats
Result
A Structure with following values
Resulting Structure
| page_tab_id | |
| home_team | |
| away_team | |
| home_score | |
| away_score | |
| game_period | |
| period_time_secs | |
| league_name | |
| stats |
Description
Obtain current values for player stats
Result
A Structure with following values
Resulting Structure
| home_stats | An array with structure similar to stats in the event per player |
| away_stats | An array with structure similar to stats in the event per player |
Description
Get a list of Video on Demand files.
Input Parameters
| page | What section is requested: waiting, staging or finished |
Result
An array of following structures
Resulting Structure
| option_id | |
| page_tab_id | |
| field_idx | |
| option_name | Name of the video |
| fb_photo_id | |
| fb_photo_url | |
| vimeo_video_url | Link to raw mp4 |
| vimeo_image_url | Link to raw preview |
| media_uid | Link to preview image media |
| creation_timestamp | |
| option_type | |
| description | |
| uploader_name | |
| uploader_email | |
| fan_id | |
| is_approved | |
| vote_count | |
| negative_vote_count | |
| is_correct | |
| tag_id | |
| tag_name | |
| activity_id | |
| share | |
| impressions | |
| clicks | |
| vimeo_key | This field is used to initialize embedded vimeo player |
| props |
Description
Get a list of Live video endpoints.
Input Parameters
| session_uid | Session Identifier |
Result
An array of following structures
Resulting Structure
| live_feed | Primary Feed Object |
| additional_feeds | Array of additional feeds ( same format) |
| feed_name | |
| vimeo_event_key | |
| video_endpoint_uid | |
| media_uid | |
| is_gated | Whether feed is not normally public |
| location_gate_metro_areas | Feed should only be accessed by fans from these metro areas, if specified. |
Description
Get room info including members
Input Parameters
| session_uid | A valid session identifier for logged in user |
| room_name |
Result
A Structure with following values
Resulting Structure
| room | a dictionary of data related to the requested room |
| room_members | a list of dictionaries containing info about the members of the requested room |
Description
Join a room, leave a room, create a room, or add friends to an existing room.
Input Parameters
| session_uid | A valid session identifier for logged in user |
| room_name | A valid room name that contains only alphanumeric characters and underscores. Max character limit of 128 |
| action | join/leave/create/add |
| is_private | when using the create action, specifies if the created room should be private. Default False |
| room_members | a list of fan_ids for the create and add actions |
Result
True or False
Description
Lookup a fan's friend status by fan_id or display_name
Input Parameters
| session_uid | A valid session identifier for logged in user |
| fan_id | |
| display_name |
Result
A Structure with following values
Resulting Structure
| fan_id | fan_id of the friend you want to lookup |
| display_name | display_name of the friend you want to lookup |
| friend_status | One of approved, requested, rejected, None |
