Fan Marketing Awards 2025
The best of fan marketing from the past year
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.
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.
There is a limit to how often you can call Tradable Bits. Currently, it's set to
600 calls per minute. If you need a higher limit, please reach out to us.
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: 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.
Segments Calls
GET /v1/segments
Description
Required Scope: segments
List available segments on the account. Will return three types of segments: tags, snapshots, and existing search filters
ResultArray of Objects
Resulting Structure| segment_type | tag/filter/snapshot |
| segment_id | If on the segment. ID is unique with in corresponding segment type |
| segment_name | Character descriptor for the segment |
GET /v1/segments/<segment_type>/<segment_id>/status
Description
Required Scope: segments
Obtain the status of a given segment including metrics on the size and fans
ResultDictionary with following metrics
Resulting Structure| fan_count | |
| email_count | |
| phone_count | |
| phone_subscribe_count | |
| email_subscribe_count | |
| last_update_timestamp | Update for the last update of the fan |
GET /v1/segments/<segment_type>/<segment_id>
Description
Required Scope: segments
Get list of fans tied to the segment. Object returned is minimalistic object as it's meant to be used for communication
Input Parameters| 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. If skipped, 1000 will be used |
Dictionary with meta and data elements. meta may include search_uid if output has to be paged.
Resulting Structure| fan_id | Primary key for the fan |
| 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 |
Crm Calls
GET /v1/crm/activity_stats
Description
Required Scope: crm
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 |
Array of Counters
Resulting Structure| account_id | |
| campaign_title | |
| property_name | |
| counter |
GET /v1/crm/campaigns
Description
Required Scope: crm
Get a list of Campaigns on the account.
Input Parameters| q | Text based filter to specific campaigns |
Array of structures
Resulting Structure| account_id | |
| title | |
| page_tab_id | |
| stream_key | |
| app_type | |
| is_active | |
| creation_timestamp | |
| winner_fan_id |
GET /v1/crm/activities
Description
Required Scope: crm
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 500 |
| 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 |
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) |
| opted_in_business_ids | Opted in business ids of the fan |
| is_subscribed | Opted in to Email Marketing |
| is_phone_subscribed | Opted in to SMS Marketing |
| 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 |
POST /v1/crm/activities
Description
Required Scope: crm
Submit new Activity as well as Fan details for data integration
Input Parameters| first_name | |
| last_name | |
| email * | |
| phone | |
| campaign_title | |
| province | |
| postal_code | |
| country_code | |
| is_subscribed | |
| is_phone_subscribed |
Array
Resulting Structure| fan_id | |
| activity_id |
GET /v1/crm/activities/<page_tab_id>/leaderboard
Description
Required Scope: crm
Fetch top 10 performing fans for a campaign
Input Parameters| 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 |
An array of structures with following fields
Resulting Structure| 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) |
GET /v1/crm/fan_tags
Description
Required Scope: crm
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 |
Array
Resulting Structure| tag_name | |
| tag_id | |
| fan_id | |
| creation_timestamp | |
| first_name | |
| last_name | |
GET /v1/crm/fans
Description
Required Scope: crm
Search for Fan records using CRM Search interface
Input Parameters| include_recent_entry | Include latest campaign into payload on result |
| include_tags | Include fan tags into payload on result |
| include_business_opt_ins | Include business opt ins into payload on result |
| 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_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 |
Array with Meta structure as part of result
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags | |
| last_page_tab_id | |
| last_campaign_name | |
| opted_in_business_ids |
GET /v1/crm/fan_updates
Description
Required Scope: crm
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 | 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. |
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 | |
| account_id | |
| first_name | |
| last_name | |
| latitude | |
| longitude | |
| city | |
| province | |
| country_code | |
| metro_area | |
| postal_code | |
| ip_address | |
| is_optout | |
| is_subscribed | |
| is_phone_subscribed | |
| gender | |
| rating | |
| birth_date | |
| phone | |
| add_phone | |
| is_confirmed | |
| is_phone_confirmed | |
| display_name | |
| tags | |
| fields | |
| last_page_tab_id | |
| last_campaign_name | |
| fan_time_key | |
| creation_timestamp | |
| last_update_timestamp | |
| creation_timestamp_iso | ISO creation timestamp |
| last_update_timestamp_iso | ISO last update timestamp |
GET /v1/crm/points
Description
Required Scope: crm
Get a fan leaderboard based on provided filters
Input Parameters| start_date * | yyyy-mm-dd |
| end_date * | yyyy-mm-dd |
| point_name * | |
| performance_uid | Optional. Filter point counts by a specific performance. |
Array with Meta structure as part of result
Resulting Structure| 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 |
POST /v1/crm/purchases
Description
Required Scope: crm
Upsert purchases via API.
Input Parameters| 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. |
| 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. |
The newly created or updated purchase.
Resulting Structure| purchase_key | A unique key for this purchase. |
| fan_id | The fan ID associated with this purchase. |
GET /v1/crm/purchases
Description
Required Scope: crm
Search for purchases for specific products, from a specific merchant and/or location, within a date range. Responses are paginated.
Input Parameters| network * | The network that the purchase originated from. |
| start_date * | All purchases made after this date will be returned. |
| end_date * | All purchases made before this date will be returned. |
| product_name | A product name, this field is a search field so all product names which contain this string will be returned. |
| merchant_key | Only return purchases which come from a specific merchant. |
| location_key | Only return purchases which are from a specific location. |
| next_purchase_key | Used for pagination, each response will contain a next_purchase_key field if there is more data to be fetched. |
Structure: {'meta': {'page_size': 500, 'next_purchase_key': 'somestring', 'count': 30}, 'data':[] }. Data is array with following elements
Resulting Structure| 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 as a unix timestamp. |
| 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. |
| 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. |
| order_timestamp_iso | The order timestamp in ISO format. |
GET /v1/crm/tickets
Description
Required Scope: crm
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 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 |
| 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 |
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 |
| is_deleted | True if ticket deleted |
| last_updated_timestamp | ISO date of last update |
GET /v1/crm/tickets/<ticket_id>
Description
Required Scope: crm
Get single ticket by ticket id
ResultSingle record. 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 |
| is_deleted | True if ticket deleted |
| last_updated_timestamp | ISO date of last update |
POST /v1/crm/tickets
Description
Required Scope: crm
Create new ticket and Corresponding Fan Record
Input Parameters| first_name * | |
| last_name * | |
| email * | |
| purchase_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| paid_amount * | Numeric value for line item |
| num_seats * | Number of seats purchased |
| event_date * | ISO8601 Encoded String |
| event_name * | |
| phone | |
| 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 | Subscribed to email |
| is_phone_subscribed | Subscribed to phone |
| city | |
| province | |
| postal_code | |
| country_code | |
| artist_name | |
| venue_name | |
| event_key | |
| network | |
| order_key | |
| is_deleted | Boolean value |
| fan_source | Text identifier if fan is to be created |
Created Record.
Resulting Structure| ticket_id | |
| ticket_key | |
| fan_id | |
| status | success or duplicate if ticket already exists |
POST /v1/crm/bulk_tickets
Description
Required Scope: crm
Create up to 100 new tickets and Corresponding Fan Records. Takes in a list of tickets with the same structure and requirements as POST /v1/crm/tickets
Input Parameters| first_name * | |
| last_name * | |
| email * | |
| paid_amount * | Numeric value for line item |
| num_seats * | Number of seats purchased |
| purchase_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| event_date * | ISO8601 Encoded String |
| event_name * | |
| event_key * | |
| phone | |
| customer_key | Key of the customer in the remote system |
| ticket_key | Unique identifier for the line item (i.e. unique per price code and amount). |
| price_code | Price level or code of line item |
| is_subscribed | Subscribed to email |
| is_phone_subscribed | Subscribed to phone |
| city | |
| province | |
| postal_code | |
| country_code | |
| artist_name | |
| venue_name | |
| network | |
| order_key | |
| is_deleted | Boolean value |
A list of Created Records.
Resulting Structure| ticket_id | |
| ticket_key | |
| fan_id | |
| status | success or duplicate if ticket already exists |
GET /v1/crm/tickets/events
Description
Required Scope: crm
Get all event tickets or search by event_name, event_key, event_date or venue_name
Input Parameters| 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 |
Structure: {'meta': { 'count': ### }, 'data': []}. Data is an array with the following elements
Resulting Structure| 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 |
POST /v1/crm/tickets/events
Description
Required Scope: crm
Create, update or delete a ticket event.
Input Parameters| 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 |
Info on created/updated/deleted record.
Resulting Structure| event_uid | |
| action | |
| status | success |
GET /v1/crm/ticket_stats
Description
Required Scope: crm
Get stats for tickets over a specified time range.
Input Parameters| 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 |
Single record. Data is an object with the following elements
Resulting Structure| returning_fans_count | |
| new_fans_count | |
| sales_count | |
| seats_count | |
| revenue |
GET /v1/crm/registrations
Description
Required Scope: crm
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 |
| Allows you to filter tickets to specific user/email address | |
| performance_uid | Allows you to filter tickets to a specific performance |
| limit | Max row count. Default = 50 |
Structure: {'meta': { 'count':xxx },'data':[] }. Data is array with following elements
Resulting Structure| 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 |
| 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 |
| activity_id | |
| is_subscribed | |
| is_phone_subscribed | |
| performance_uid | Performance UUID of the ticket event associated with the registration |
POST /v1/crm/registrations
Description
Required Scope: crm
Create new registration and Corresponding Fan Record
Input Parameters| first_name * | |
| last_name * | |
| event_name * | |
| event_date * | Date of the Event. ISO Date |
| email * | |
| registration_key * | Unique identifier for the line item |
| registration_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| network * | |
| phone | |
| venue_name | |
| barcode | |
| lookup_id | |
| event_key | |
| ticket_key | |
| is_minor | |
| birth_date | |
| country_code | |
| province | |
| city | |
| postal_code | |
| address | |
| activity_id | |
| fan_id | |
| is_preferred | |
| is_subscribed | |
| is_phone_subscribed | |
| order_key |
Created Record.
Resulting Structure| registration_key | Unique Identifier for the registration |
| fan_id | Fan ID associated with this registration |
GET /v1/crm/registrations/scans
Description
Required Scope: crm
Get registration and scan data by scan_group_name. Results are ordered by scan_key ascending.
Input Parameters| scan_group_name * | scan_group_name / group_set_name identifier for different groups of scans. |
| 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 and registration data.
Resulting Structure| 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. |
| site_id | The integer ID for the site. |
| node_name | |
| zone_name | |
| scan_timestamp | The time that scan occurred |
| registration_key | The registration key. |
| ticket_order_key | The order key of the associated ticket. |
| 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 |
| first_name | |
| last_name | |
| phone | |
| country_code | |
| province | |
| postal_code | |
| registration_timestamp | Timestamp when registration occurred |
| barcode | Wristband barcode associated with this scan/registration. |
POST /v1/crm/fans
Description
Required Scope: crm
Create new Fan Record
Input Parameters| first_name | |
| last_name | |
| Either Email or Phone is required | |
| password | |
| display_name | |
| 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. |
| fan_source | Text identifier if fan is to be created |
| is_optout | |
| idol_names | Array of idol names to associate as fan idols |
Created Record
Resulting Structure| fan_id |
POST /v1/crm/idol_fans
Description
Required Scope: crm
Create new Idol Fan record
Input Parameters| idol_fans |
Array of stringified JSON objects of following structure. Either email/phone or user_key + network are required on each item in the array
|
JSON object detailing created records
Resulting Structure| inserted |
JSON object with info on inserted records
|
||||
| errors |
Array of JSON objects detailing which rows failed insertion
|
DELETE /v1/crm/idol_fans
Description
Required Scope: crm
Delete Idol Fan record
Input Parameters| fan_id * | |
| idol_uid * |
Boolean Value of True
GET /v1/crm/fans/<fan_id>/identifiers
Description
Required Scope: crm
Get fan identifiers for a specific Fan ID
ResultA list of fan identifiers
Resulting Structure| account_id | |
| fan_id | |
| network | |
| identifier_value | |
| creation_timestamp | |
| creation_timestamp_iso |
POST /v1/crm/fans/<fan_id>/identifiers
Description
Required Scope: crm
Create a fan identifier for a specific Fan ID
Input Parameters| network | |
| identifier_value |
Boolean Value of True
DELETE /v1/crm/fans/<fan_id>/identifiers
Description
Required Scope: crm
Delete a fan identifier for a specific Fan ID
Input Parameters| network | |
| identifier_value |
Boolean Value of True
GET /v1/crm/fans/<fan_id>
Description
Required Scope: crm
Get Specific fan record via ID
ResultFollowing structure
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
POST /v1/crm/fans/<fan_id>
Description
Required Scope: crm
Update Fan Record
Input Parameters| first_name | |
| last_name | |
| password | |
| display_name | |
| gender | Must be male, female, diverse, other, or empty. |
| is_subscribed | true/false/on/off |
| is_phone_subscribed | |
| phone | |
| birth_date | |
| ip_address | |
| country_code | |
| province | If used, country_code is required |
| city | If used, country_code is required |
| postal_code | If used, country_code is required |
| 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. |
Updated Record
Resulting Structure| fan_id |
DELETE /v1/crm/fans/<fan_id>
Description
Required Scope: crm
Delete Record
ResultBoolean value of True
GET /v1/crm/fans/<fan_id>/points
Description
Required Scope: crm
Get Fan points
ResultFollowing structure
Resulting Structure| fan_id | |
| point_uid | |
| point_name | |
| point_count |
POST /v1/crm/fans/<fan_id>/points
Description
Required Scope: crm
award a fan points
Input Parameters| point_name * | |
| point_count * |
Updated Record
Resulting Structure| fan_id | |
| fan_point_uid |
GET /v1/crm/fans/<fan_id>/idols
Description
Required Scope: crm
Fetch list of idols for a given Fan
Input Parameters| label_name | Limit Idols to a specific label |
| idol_uid | Filter by specific idol_uid |
Array of Idols
Resulting Structure| account_id | |
| idol_uid | |
| idol_name | |
| idol_type | |
| description | |
| is_explicit | is_explicit flag |
| creation_timestamp | |
| last_update_timestamp | |
| idol_labels | An array of labels associated with this idol. |
POST /v1/crm/fans/<fan_id>/idols
Description
Required Scope: crm
Add or remove idol association
Input Parameters| action * | add/delete |
| idol_uid | One of idol_uid or idol_name is required. |
| idol_name | Name for a given (as alternative to UUID). One of idol_uid or idol_name is required. |
| is_explicit | is_explicit boolean flag, optional. |
Following structure
Resulting Structure| fan_id | |
| idol_uid |
GET /v1/crm/fans/<fan_id>/registrations
Description
Required Scope: crm
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 |
Array of records
Resulting Structure| 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 |
| 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 |
| activity_id | |
| is_subscribed | |
| is_phone_subscribed |
POST /v1/crm/fans/<fan_id>/registrations
Description
Required Scope: crm
Create new Registration Record for a given Fan
Input Parameters| first_name * | |
| last_name * | |
| event_name * | |
| event_date * | Date of the Event. ISO Date |
| network * | |
| email * | |
| registration_key * | Unique identifier for the line item |
| registration_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| phone | |
| venue_name | |
| barcode | |
| lookup_id | |
| event_key | |
| ticket_key | |
| is_minor | |
| birth_date | |
| country_code | |
| province | |
| city | |
| postal_code | |
| address | |
| activity_id | |
| is_preferred | |
| is_subscribed | |
| is_phone_subscribed | |
| order_key |
Array of latest registrations
Resulting Structure| fan_id | |
| registration_key |
GET /v1/crm/fans/<fan_id>/activities
Description
Required Scope: crm
Obtain a list of activities for a given Fan
Input Parameters| limit | Record Limit |
| campaign_title | Limit results to specific campaign |
Array of records
Resulting Structure| account_id | |
| fan_id | |
| creation_date | |
| campaign_title | |
| props |
POST /v1/crm/fans/<fan_id>/activities
Description
Required Scope: crm
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 |
structure with possible fan_id and activity_id if successful
Resulting Structure| fan_id | |
| activity_id |
GET /v1/crm/fields
Description
Required Scope: crm
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 |
GET /v1/crm/search_filters
Description
Required Scope: crm
Get array of search filters
Input Parameters| group name | Filter group name |
| creation_start_date | String in the form 'YYYY-MM-DD' |
| creation_end_date | String in the form 'YYYY-MM-DD' |
Array of search filters
Resulting Structure| filter_uid | |
| filter_name | |
| account_id | |
| creation_timestamp | |
| last_search_count |
GET /v1/crm/fan_stats
Description
Required Scope: crm
Get stats pertaining to fans captured by the filter provided
Input Parameters| filter_name * |
Fan stats object based on filter supplied
Resulting Structure| fans | Object containing general information such as total number of fans |
| fan_demographics | Object containing gender and fan rating breakdowns |
| top_countries | Object showing fan locations by country |
| top_metro_areas | Object showing fan locations by metro area |
| top_locations | Object showing fan locations by region with further breakdowns |
| fan_metrics | Age, gender, and rating counts |
| postal_demographics | Census breakdown percentages by ethnicity, education, income, family makeup |
GET /v1/crm/monitored_ip_addresses
Description
Required Scope: crm
Get list 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 allowed |
| creation_timestamp |
POST /v1/crm/monitored_ip_addresses
Description
Required Scope: crm
Block or allow an IP address or CIDR
Input Parameters| ip_address * | IP Address or CIDR |
| is_blocked * | True to ban users at this ip address, false to allow them |
| page_tab_id | If included, will ban or allow the given address for only this page tab |
The created record
Resulting Structure| page_tab_id | |
| ip_address |
DELETE /v1/crm/monitored_ip_addresses
Description
Required Scope: crm
Delete a blocked or allowed IP Address
Input Parameters| ip_address * | IP Address or CIDR |
| is_blocked * | |
| page_tab_id |
Boolean value of True
GET /v1/crm/points/<point_uid>/point_tiers
Description
Required Scope: crm
Get a list of point tiers belonging to a point category
Input Parameters| tier_name | Optionally filter by tier name |
list of point tier objects
Resulting Structure| point_tier_uid | |
| account_id | |
| point_uid | |
| point_name | |
| tier_name | |
| min_points | |
| creation_timestamp |
POST /v1/crm/points/<point_uid>/point_tiers
Description
Required Scope: crm
Create or update a point tier
Input Parameters| tier_name * | The name of the point tier |
| min_points * | Integer representing the lower cutoff for this point tier |
| point_tier_uid | Optional UUID for updating and existing point tier |
A point tier object
Resulting Structure| point_tier_uid | |
| account_id | |
| point_uid | |
| point_name | |
| tier_name | |
| min_points | |
| creation_timestamp |
GET /v1/crm/fans/<fan_id>/point_tier
Description
Required Scope: crm
Return the point tier of a fan in a given point category
Input Parameters| point_name * | The name of the associated point category |
A point tier object
Resulting Structure| point_tier_uid | |
| account_id | |
| point_uid | |
| point_name | |
| tier_name | |
| min_points | |
| creation_timestamp |
Ent Calls
GET /v1/ent/performances
Description
Required Scope: misc
Get all account performances
ResultList of performance records
Resulting Structure| performance_uid | Identifier for performance |
| account_id | |
| performance_name | |
| performance_date | |
| fb_ad_account_id | |
| metro_area | Venue metro area |
| creation_timestamp | |
| onsale_date | |
| venue_name | |
| display_venue_name | |
| promoter | |
| artist_name | |
| additional_artist_names | |
| campaign_event_key | |
| province | Venue Province |
| country_code | Venue Country Code |
| city | Venue City |
| performance_url | |
| status | |
| announce_date | |
| buying_group | |
| notes | |
| performance_group_name | |
| venue_uid | |
| business_id | |
| fb_event_id | |
| label_name | |
| is_valid_idol | Performance is associated with a valid idol in Tbits system |
| outlet | |
| vendor | |
| referral_page_tab_id |
POST /v1/ent/performances
Description
Required Scope: misc
Create a new performance. Take note that this endpoint does not require a secret key unlike other endpoints for performances.
Input Parameters| performance_name * | |
| performance_date * | Format YYYY-MM-DD |
| onsale_date | Format YYYY-MM-DD |
| announce_date | Format YYYY-MM-DD |
| fb_ad_account_id | |
| venue_uid | |
| promoter | |
| artist_name | |
| campaign_event_key | |
| performance_url | Must begin with https:// |
| status | draft, ready, or archived |
| buying_group | Under 32 characters |
| notes | |
| performance_group_name | Under 128 characters |
| business_id | |
| fb_event_id | |
| label_name | |
| additional_artist_names | List of strings |
| outlet | |
| vendor | |
| referral_page_tab_id |
New performance record
Resulting Structure| performance_uid | Identifier for performance |
GET /v1/ent/performances/<performance_uid>
Description
Required Scope: misc
Get single performance
ResultSingle performance records
Resulting Structure| performance_uid | Identifier for performance |
| account_id | |
| performance_name | |
| performance_date | |
| fb_ad_account_id | |
| metro_area | Venue metro area |
| creation_timestamp | |
| onsale_date | |
| venue_name | |
| display_venue_name | |
| promoter | |
| artist_name | |
| additional_artist_names | |
| campaign_event_key | |
| province | Venue Province |
| country_code | Venue Country Code |
| city | Venue City |
| performance_url | |
| status | |
| announce_date | |
| buying_group | |
| notes | |
| performance_group_name | |
| venue_uid | |
| business_id | |
| fb_event_id | |
| label_name | |
| is_valid_idol | Performance is associated with a valid idol in Tbits system |
| outlet | |
| vendor | |
| referral_page_tab_id |
POST /v1/ent/performances/<performance_uid>
Description
Required Scope: misc
Update performance
Input Parameters| performance_name * | |
| performance_date * | Format YYYY-MM-DD |
| onsale_date | Format YYYY-MM-DD |
| announce_date | Format YYYY-MM-DD |
| fb_ad_account_id | |
| venue_uid | |
| promoter | |
| artist_name | |
| campaign_event_key | |
| performance_url | Must begin with https:// |
| status | draft, ready, or archived |
| buying_group | Under 32 characters |
| notes | |
| performance_group_name | Under 128 characters |
| fb_event_id | |
| label_name | |
| additional_artist_names | List of strings |
| outlet | |
| vendor | |
| referral_page_tab_id |
Updated performance record
Resulting Structure| performance_uid | Identifier for performance |
DELETE /v1/ent/performances/<performance_uid>
Description
Required Scope: misc
Delete performance
ResultBoolean value of True
GET /v1/ent/businesses/<business_id>/quests
Description
Required Scope: apps
Get quests
Input Parameters| performance_uid | Optional filter to search quests by performance_uid |
An array of quest objects
Resulting Structure| page_tab_id | |
| performance_uid | |
| quest_type | |
| target_page_tab_id | |
| scan_group_names | |
| is_required | |
| access_restriction_type | |
| fan_points_required | |
| quest_title | |
| button_text | |
| quest_description | |
| reward_type | |
| fan_points_reward | |
| atvenu_sales_event_key | |
| atvenu_promo_key | |
| creation_timestamp | |
| bestring_location_group_id | |
| bestring_promotion_id | |
| required_page_tab_ids | |
| link_url | |
| start_date | |
| end_date | |
| point_uid | |
| site_name |
POST /v1/ent/businesses/<business_id>/quests
Description
Required Scope: apps
Create a quest
Input Parameters| performance_uid | Optionally assign quest to a performance. Required when quest_type is scan or wristband, and when the reward_type is atvenu or bestring |
| target_page_tab_id | |
| site_name | |
| scan_group_names[] | |
| link_url | |
| quest_type * | Must be one of 'scan', 'campaign', 'quickpicks', 'wristband', 'link_url', or 'custom' |
| is_required | |
| fan_points_required | |
| access_restriction_type | |
| required_page_tab_ids[] | |
| reward_type | |
| bestring_location_group_id | |
| bestring_promotion_id | |
| atvenu_sales_event_key | |
| atvenu_promo_key | |
| fan_points_reward | |
| quest_title * | |
| button_text | |
| quest_description | |
| start_date | |
| end_date |
ID of entity created
Resulting Structure| page_tab_id |
DELETE /v1/ent/businesses/<business_id>/quests/<page_tab_id>
Description
Required Scope: apps
Delete quest
ResultHTTP 200
GET /v1/ent/businesses/<business_id>/rewards
Description
Required Scope: apps
Get quest rewards
Input Parameters| performance_uid | Optionally filter by performance. |
An array of reward objects
Resulting Structure| reward_uid | |
| business_id | |
| performance_uid | |
| reward_title | |
| reward_type | |
| atvenu_sales_event_key | |
| atvenu_promo_key | |
| fan_points_required | |
| creation_timestamp | |
| bestring_location_group_id | |
| bestring_promotion_id | |
| point_uid | |
| point_tier_uid |
POST /v1/ent/businesses/<business_id>/rewards
Description
Required Scope: apps
Create a reward
Input Parameters| reward_title * | |
| reward_type * | |
| fan_points_required | Either this or point_tier_uid is required |
| point_tier_uid | Either this or fan_points_required is required |
| performance_uid | Optionally assign reward to a performance. Required when reward_type is atvenu or bestring. |
| atvenu_sales_event_key | |
| atvenu_promo_key | |
| bestring_location_group_id | |
| bestring_promotion_id |
ID of entity created.
Resulting Structure| reward_uid |
DELETE /v1/ent/businesses/<business_id>/rewards/<reward_uid>
Description
Required Scope: apps
Delete a reward
ResultHTTP 200
GET /v1/ent/fans/<fan_id>/events
Description
Required Scope: crm
Fetch list of idol events/performances for a given Fan
Input Parameters| idol_label_name | Limit Idol Events to a specific label |
| idol_uid | Filter Idol Events by specific idol_uid |
Array of Idols Events and Array of Performances
Resulting Structure| idol_events |
Array of objects
|
||||||||||||||
| performances |
Array of objects
|
POST /v1/ent/fans/<fan_id>/idols/events
Description
Required Scope: crm
Associate fan to an idol event or update the state of the association
Input Parameters| idol_event_uid * | UUID of the Idol Event to associate the fan to |
| state | One of 'saved', 'going', 'verified', or 'registered'. Defaults to 'saved'. |
Following structure
Resulting Structure| fan_id | |
| idol_event_uid | |
| state | One of 'saved', 'going', 'verified', or 'registered'. |
DELETE /v1/ent/fans/<fan_id>/idols/events
Description
Required Scope: crm
Remove fan association to an idol event. Can only be removed if the state is 'saved'.
Input Parameters| idol_event_uid * | UUID of the Idol Event to remove the fan from |
Boolean value of True
POST /v1/ent/fans/<fan_id>/performances
Description
Required Scope: crm
Associate fan to a performance or update the state of the association
Input Parameters| performance_uid * | UUID of the Performance to associate the fan to |
| states | Array of states for the performance fan. Minimum 1, maximum 3. Valid states are 'saved', 'going', 'verified', or 'registered'. Defaults to ['saved']. |
Following structure
Resulting Structure| fan_id | |
| performance_uid | |
| states | Array of states for the performance fan. Minimum 1, maximum 3. Valid states are 'saved', 'going', 'verified', or 'registered'. |
DELETE /v1/ent/fans/<fan_id>/performances
Description
Required Scope: crm
Remove fan association to a performance. Can only be removed if the only state in the state array is 'saved'.
Input Parameters| performance_uid * | UUID of the Performance to remove the fan from |
Boolean value of True
GET /v1/ent/fan_points
Description
Required Scope: crm
Get a list of currently awarded fan points
Input Parameters| start_date * | yyyy-mm-dd. |
| end_date * | yyyy-mm-dd. |
| point_uid | Optionally filter by point |
| fan_id | Optionally filter by fan |
| order | Valid options are 'leaderboard' or 'desc'. Default = 'asc' |
| limit |
| fan_point_uid | |
| fan_id | |
| point_uid | |
| creation_timestamp | |
| point_count | |
| page_tab_id | |
| ip_address | |
| point_source | |
| session_uid | |
| award_signature | |
| activity_id | |
| point_type | |
| props | |
| performance_uid | |
| reward_uid | |
| point_name | |
| display_name |
POST /v1/ent/fan_points
Description
Required Scope: crm
Award fan points
Input Parameters| point_uid * | Point for the points to be associated with |
| fan_id * | Fan for the points to be associated with |
| point_count * | Number of points to award (can be negative) |
| point_type | One of 'points', 'atvenu', 'bestring'. Defaults to 'points' |
| reward_uid | Optionally associate the points with a reward |
| page_tab_id | Optionally associate the points with a campaign |
| activity_id | Optionally associate the points with an activity |
| session_uid | Optionally associate the points with a fan session |
| award_key | Optional deduplication key |
| fan_point_uid |
POST /v1/ent/check_display_name
Description
Required Scope: crm
Check if a display name exists and is valid
Input Parameters| display_name |
Either a valid display name (modified if the display name is taken), or an error if the display name is invalid
POST /v1/ent/businesses/<business_id>/quests/<page_tab_id>/fans/<fan_id>/complete
Description
Required Scope: apps
Mark a fan as having completed a quest, and award any relevant participation incentives
Input Parameters| lookup_id | If specified, the system will attempt to link the provided wristband id to the fan before assigning any quest completions. This field is required for wristband type quests. |
| activity_id | id of new quest completion |
GET /v1/ent/businesses/<business_id>/quests/fans/<fan_id>/complete
Description
Required Scope: apps
Get the completion status of a fan for quests of a certain business
Input Parameters| performance_uid | optionally filter to specific performance |
Structure: {page_tab_id: boolean} for each quest. The boolean value indicates quest completion.
Streams Calls
GET /v1/streams
Description
Required Scope: streams
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 |
GET /v1/streams/<stream_key>/records
Description
Required Scope: streams
Search for approved records in the stream
Input Parameters| networks | |
| label_key | |
| sku | |
| is_graphic | yes, no or empty |
| 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 |
{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
Required Scope: streams
Create new Stream Record
Input Parameters| email * | |
| name | Name is required if email does not exist |
| image_url | |
| caption | |
| latitude | |
| longitude | |
| labels | Comma separated list of labels |
| props_* | Ability to store any meta data as part of the record |
Newly Created Record
Resulting Structure| feed_record_id |
GET /v1/streams/<stream_key>
Description
Required Scope: streams
Get Summary Stats on the stream
Input Parameters| data | Comma separated list of sections: words, hashtags, labels |
| label_key | Label Filter |
| start_time | Date filter (specified as unix time) |
| end_time | Date filter (specified as unix time) |
Summary Structure Record
Resulting Structure| stream_key | |
| stream_name | |
| total_stored | |
| total | |
| approved_total | |
| authors | |
| reach | |
| last_record_timestamp | |
| words | |
| hashtags | |
| labels |
GET /v1/streams/<stream_key>/<feed_record_id>
Description
Required Scope: streams
Get individual record
ResultRecord 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 |
POST /v1/streams/<stream_key>/<feed_record_id>
Description
Required Scope: streams
Approve individual Record or Label it accordingly
Input Parameters| action * | approve/remove/label/unlabel |
| label_key |
Update Record Data
Resulting Structure| feed_record_id |
Sessions Calls
POST /v1/sessions/wifi_fans
Description
Required Scope: sessions
This endpoint enables third party apps to pass Wifi Authentication Information
Input Parameters| network * | Connected network. Network value can drive other require arguments. Supported: email |
| email * | |
| first_name | |
| last_name | |
| activity_name | Reference to the Activity or Event name. |
| device_id | Hardware reference if mobile app is used |
| device_network | one of ios/android |
True if call is successful, error otherwise
GET /v1/sessions/check
Description
Required Scope: sessions
Quick endpoint to confirm the entity of the registered user for the purpose of handling signup
Input Parameters| phone | One of phone or email are required |
| One of phone or email are required |
Structure as below
Resulting Structure| fan_id | Fan ID of the records |
| first_name | First Name |
| last_name | Last Name |
POST /v1/sessions/signup
Description
Required Scope: sessions
This endpoint enables third-party apps to push email signup or some other form of activity into our CRM.
Input Parameters| One of phone or email are required | |
| phone | One of phone or email are required |
| 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 | 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 |
Structure as below
Resulting Structure| fan_id | Fan ID of the records |
| activity_id | Activity ID if it was created properly |
POST /v1/sessions/connect
Description
Required Scope: sessions
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 | Type of the action to perform during authentication. Supported values: '' - get guest session, 'register' - register new fan, given that existing credentials don't exist yet, 'email' - check for email record,'phone'- check for phone, 'verify_sms' - generate sms message for login, 'verify_email' - generate email message for login, 'submit_verification_code' - send verification code to generate session, 'password' - login using password and either email or phone |
| business_id * | |
| page_tab_id | |
| ip_address | |
| last_name | |
| first_name | |
| phone | |
| password | |
| is_accepted | Flag to confirm terms acceptance. Required if terms_required is returned |
| request_uid | Required for submit_verification_code |
| verification_code | Required for submit_verification_code |
| device_id | |
| device_network |
On success, there will be a new session object as described below. On failure or mid-step (e.g. sms verify), a different structure will be returned
Resulting Structure| session_uid | |
| fan_id | |
| account_id | |
| props | |
| expiration_timestamp |
GET /v1/sessions/<session_uid>
Description
Required Scope: sessions
Get existing Session using ID
ResultRecord
Resulting Structure| session_uid | |
| fan_id | |
| account_id | |
| props | |
| expiration_timestamp |
GET /v1/sessions/<session_uid>/fan
Description
Required Scope: sessions
Fetch current Fan Record
ResultFollowing Structure
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| image_url | |
| gender | |
| tags |
POST /v1/sessions/<session_uid>/fan
Description
Required Scope: sessions
Update Current Fan Record
Input Parameters| first_name | |
| last_name | |
| password | |
| 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 |
Updated Record
Resulting Structure| fan_id |
GET /v1/sessions/<session_uid>/points
Description
Required Scope: sessions
Get Fan points
ResultFollowing structure
Resulting Structure| fan_id | |
| point_uid | |
| point_name | |
| point_count |
Idols Calls
POST /v1/idols
Description
Required Scope: idols
Create new idol in the database
Input Parameters| idol_name * | Name of the new idol |
| spotify_uid | Optional Spotify UID if it's available |
| artist_id | Optional Artist ID |
| discovery_id | Optional Discovery ID |
| idol_type | Optional idol type. Valid options are 'artist', 'sponsor', 'podcast', 'team', or 'other'. If the type 'artist' is specified then a 'spotify_uid' is required, otherwise 'spotify_uid' must be empty if any other type is specified |
| label_names | Array of label names to assign to Idol |
| props | Additional Information. Valid options are 'fun_fact', 'new_award', 'world_ranking', 'catchphrase', 'new_single'. Input must be a valid, serialized JSON string. Please note that the props field must be sent with every POST request, else they will be deleted. New props can be sent anytime, and will override old ones. |
idol structure
Resulting Structure| idol_uid |
GET /v1/idols
Description
Required Scope: idols
Search for an idols in the database
Input Parameters| idol_name | Search Expression for an idol |
| label_name | Limit Idols to a specific label |
Array of idol structures
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| link_url | |
| idol_type | |
| idol_labels | An array of labels associated with this idol. |
GET /v1/idols/<idol_uid>
Description
Required Scope: idols
Obtain an idol for a given idol_uid
ResultA structure for a given idol as follows
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| link_url | |
| props | Additional Information. Valid options are 'fun_fact', 'new_award', 'world_ranking', 'catchphrase', 'new_single'. Please note that the props field must be sent with every POST request, else they will be deleted. New props can be sent anytime, and will override old ones. |
| idol_type | |
| idol_labels | An array of labels associated with this idol. |
GET /v1/idols/events
Description
Required Scope: idols
Based on the search parameters return a list of Idol Events.
Input Parameters| idol_uid | |
| performance_uid | Used to fetch Idol Events associated with a specific Performance |
| venue_name | |
| q | |
| label_name | |
| start_date | |
| end_date | |
| display_date | Search by the assigned display date of the event (start_date and end_date will be ignored). |
Array of JSON records matching the search
Resulting Structure| idol_event_uid | |
| account_id | |
| idol_uid | |
| start_timestamp | |
| end_timestamp | |
| venue_name | |
| city | |
| province | |
| country_code | |
| event_url | |
| ticket_url | |
| label_name | |
| idol_name | |
| media_uid | |
| description | |
| ticket_event_uid | |
| performance_uid | |
| performance_name | |
| is_available | |
| idol_image_url | |
| idol_media_uid | |
| last_update_timestamp | |
| show_on_previous_day | Assign event to previous day of festival (boolean). |
| display_date | Event date (day before date of start_timestamp if show_on_previous_day is true) |
Reports Calls
GET /v1/reports
Description
Required Scope: reports
Get all shared reports associated with the current account.
ResultArray 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', 'artist_charts', 'business', 'crm', 'fb_adaccount', 'idol', 'idol_details', 'sms', 'stream', 'ticket_compare', 'ticket_geo', 'ticket_sales', '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 |
GET /v1/reports/<report_uid>
Description
Required Scope: reports
Get data for a shared report.
ResultStructure: {'<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
POST /v1/ads/projects/<project_uid>/budget_lines
Description
Required Scope: ads
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 |
JSON object as per structure below
Resulting Structure| project_line_uid |
Misc Calls
GET /v1/trackers
Description
Required Scope: misc
Get a list of recently created Trackers (last 500 trackers). The date range will default to searching between now and 31 days in the past if neither option is specified
Input Parameters| min_creation_date | Minimum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
| max_creation_date | Maximum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
Array of JSON objects as per structure below
Resulting Structure| tracker_id | Unique identifier for tracker |
| account_id | Account id associated with the tracker |
| creation_timestamp | UNIX timestamp for creation |
| tracker_name | Name for the tracker |
| tracker_group_name | |
| target_url | |
| virtual_domain | |
| tracker_key | |
| purchase_event_wildcard | Purchase event name wildcard, used to match purchase events to trackers. |
| tracker_url | |
| tracker_marketing_group_name | |
| network | |
| attributed_purchase_count | |
| attributed_purchase_amount | |
| total_tracker_click_count | |
| creation_timestamp_iso | Formatted yyyy-mm-dd : hh:mm:ss timestamp |
GET /v1/trackers/<tracker_id>
Description
Required Scope: misc
Get individual tracker as specified by ID. The date range will default to searching between now and 31 days in the past if neither option is specified
Input Parameters| min_creation_date | Minimum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
| max_creation_date | Maximum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
The following JSON structure will be returned if a tracker with the inputted ID exists for your account. Otherwise an error will be returned
Resulting Structure| tracker_id | Unique identifier for tracker |
| account_id | Account id associated with the tracker |
| creation_timestamp | UNIX timestamp for creation |
| tracker_name | Name for the tracker |
| tracker_group_name | |
| target_url | |
| virtual_domain | |
| tracker_key | |
| purchase_event_wildcard | Purchase event name wildcard, used to match purchase events to trackers. |
| tracker_url | |
| tracker_marketing_group_name | |
| network | |
| attributed_purchase_count | |
| attributed_purchase_amount | |
| total_tracker_click_count | |
| creation_timestamp_iso | Formatted yyyy-mm-dd : hh:mm:ss timestamp |
POST /v1/trackers
Description
Required Scope: misc
Create New Tracker for measurement of redirect performance. This call allows for the creation of Tradable Bits Trackers
Input Parameters| virtual_domain * | Domain. Must be preconfigured and setup by Tradable Bits |
| target_url * | |
| tracker_name * | Name for the tracker, maximum 128 characters |
| tracker_group_name * | |
| network | spotify, instagram, facebook, google, X or custom. Will default to custom if not specified or not in the list of valid networks |
| tracker_key | Must be alphanumeric. One will be generated if not supplied |
| purchase_event_wildcard | Purchase event name wildcard, used to match purchase events from sales pixel to trackers. |
| tracker_marketing_group_name | Max length 64 characters |
| page_tab_id |
Following structure
Resulting Structure| tracker_id | Unique identifier for tracker |
| virtual_domain | |
| tracker_key |
GET /v1/trackers/events
Description
Required Scope: misc
Get associated with account tracker events filtering by purchase event name and is_clicked status. Endpoint is paginated, use the 'cursor' value from the 'meta' part of the response in each subsequent request.
Input Parameters| start_timestamp * | |
| end_timestamp * | |
| purchase_event_name | Optional. Used to filter for a specific purchase_event_name. |
| is_clicked | Optional boolean value. Used to filter for events which have or don't have an associated tracker click. |
| cursor | Used for paging, use the value from the previous response. |
A structure following format: {"meta":{"cursor":"xxx", "page_size": xxx}, "records":[...]}
Resulting Structure| tracker_event_uid | |
| creation_timestamp | |
| purchase_amount | |
| is_clicked | |
| tracker_id | |
| fan_id | |
| activity_id | |
| ip_address | |
| device_type | |
| province | |
| country_code | |
| purchase_event_name | |
| host_name | |
| ticket_id | |
| order_key | |
| purchase_key | |
| quantity | |
| purchase_event_details | |
| currency | |
| url_param_props |
GET /v1/props/<prop_name>
Description
Required Scope: misc
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 |
The value currently stored under this prop_name
GET /v1/geoip
Description
Required Scope: misc
Get regional information from an IP address
Input Parameters| ip_address | IPv4 or IPv6 address. otherwise caller ip will be used |
Regional information associated with that IP address
Resulting Structure| city | |
| region_name | |
| latitude | |
| longitude | |
| country_name | |
| postal_code |
GET /v1/shp_lookup
Description
Required Scope: misc
Lookup product on Shopify
Input Parameters| query |
A list of matching shopify products
POST /v1/yinzcam_subscription
Description
Required Scope: misc
Part of the integration with Yinzcam for push tokens sync
Input Parameters| user_key * | |
| push_token * | |
| device_network * |
Boolean value of True
GET /v1/account_ad_stats
Description
Required Scope: misc
Fetch ad stats for the account
Input Parameters| start_date * | |
| end_date * | |
| network |
A list of structures with the following fields
Resulting Structure| network | Ad platform, e.g. facebook, twitter |
| spend | |
| impressions | |
| clicks | |
| conversion_amount | |
| conversion_count | |
| offline_conversion_amount | |
| offline_conversion_count | |
| custom_conversion_count | |
| custom_conversion_amount | |
| custom_offline_conversion_count | |
| custom_offline_conversion_amount | |
| roas | |
| cpc | |
| cpm |
GET /v1/account_ad_stats_by_campaign
Description
Required Scope: misc
Fetch ad stats for the account, grouped by campaign
Input Parameters| start_date * | |
| end_date * | |
| network |
A list of structures with the following fields
Resulting Structure| network | Ad platform, e.g. facebook, twitter |
| ad_account_key | |
| campaign_key | |
| campaign_name | |
| spend | |
| impressions | |
| clicks | |
| conversion_amount | |
| conversion_count | |
| offline_conversion_amount | |
| offline_conversion_count | |
| custom_conversion_count | |
| custom_conversion_amount | |
| custom_offline_conversion_count | |
| custom_offline_conversion_amount | |
| roas | |
| cpc | |
| cpm |
GET /v1/template_portals
Description
Required Scope: misc
Get account template portals
ResultTemplate portal record(s)
Resulting Structure| portal_uid | |
| account_id | |
| portal_name | |
| performance_group_name | |
| password | |
| templates_created | Number of templates created |
| creation_timestamp | |
| last_access_timestamp |
GET /v1/template_portals/<portal_uid>
Description
Required Scope: misc
Get single template portal
ResultTemplate portal record
Resulting Structure| portal_uid | |
| account_id | |
| portal_name | |
| performance_group_name | |
| password | |
| templates_created | Number of templates created |
| creation_timestamp | |
| last_access_timestamp |
POST /v1/template_portals
Description
Required Scope: misc
Create template portal
Input Parameters| portal_name * | |
| performance_group_name * | |
| password | Including will require the given password when accessing the portal |
New template portal record
Resulting Structure| portal_uid |
POST /v1/template_portals/<portal_uid>
Description
Required Scope: misc
Update template portal
Input Parameters| portal_name * | |
| performance_group_name * | |
| password | Including will require the given password when accessing the portal |
Updated template portal record
Resulting Structure| portal_uid |
DELETE /v1/template_portals/<portal_uid>
Description
Required Scope: misc
Delete template portal
ResultBoolean value of True
Apps Calls
GET /v1/apps/<page_tab_id>/leaderboard
Description
Required Scope: apps
Get a Public Leaderboard
Input Parameters| session_uid | A valid session identifier for logged in user. Required for friends_only = true |
| friends_only | Only return leaderboard info for friends of the logged in user |
An array of following rows
Resulting Structure| fan_id | |
| display_name | |
| correct_answer_count | |
| points | |
| clicker_points |
GET /v1/apps
Description
Required Scope: apps
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 |
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 |
GET /v1/businesses
Description
Required Scope: apps
Get a list of businesses on the account
ResultAn 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 |
GET /v1/businesses/<business_id>
Description
Required Scope: apps
Get a specific Business record given ID
Resultstructure with following fields
Resulting Structure| legal_rules | |
| legal_terms | |
| legal_privacy | |
| business_id | |
| business_name | |
| media_map | |
| scheduler_props | |
| locale_props | |
| style_props |
GET /v1/apps/<page_tab_id>/bundle_stats
Description
Required Scope: apps
Obtain statistical data for a specific bundle campaign
Input Parameters| start_date | Date filter for stats |
| end_date | Date filter for stats |
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 |
GET /v1/apps/<page_tab_id>/stats
Description
Required Scope: apps
Obtain statistical data on executed campaign
Input Parameters| start_date | Date filter for stats |
| end_date | Date filter for stats |
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 |
GET /v1/apps/<page_tab_id>/detailed_stats
Description
Required Scope: apps
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 | Date filter |
| end_timestamp | Date filter |
| tab_item_id | Filter to specific tab items for target = wager_points |
Array of objects depending on your requested target
GET /v1/apps/<page_tab_id>/props
Description
Required Scope: apps
Get all props for a specific page tab
ResultA structure of campaign props with configured attributes
GET /v1/apps/<page_tab_id>
Description
Required Scope: apps
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. |
A structure of campaign with configured attributes
GET /v1/apps/<page_tab_id>/total_points
Description
Required Scope: apps
Fetch total fan points for a campaign
Input Parameters| start_timestamp | Date filter |
| end_timestamp | Date filter |
A structure with following fields
Resulting Structure| total_points |
GET /v1/apps/<page_tab_id>/wager_entries
Description
Required Scope: apps
Fetch entries for a wager campaign
Input Parameters| q | Query string |
| start_date | Date filter |
| end_date | Date filter |
An array of Structures with following fields
Resulting Structure| tab_item_id | |
| page_tab_id | |
| creation_date | |
| title | |
| subtitle | |
| description | |
| 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 |
GET /v1/apps/<page_tab_id>/simple_points
Description
Required Scope: apps
Fetch fan points for a campaign without any PII
Input Parameters| start_timestamp | Date filter |
| end_timestamp | Date filter |
A structure with following fields
Resulting Structure| fan_id | |
| point_count | |
| creation_timestamp |
GET /v1/apps/<page_tab_id>/simple_activities
Description
Required Scope: apps
Fetch fan activities for a campaign without any PII
ResultA structure with following fields
Resulting Structure| fan_id | |
| activity_id | |
| creation_timestamp |
POST /v1/apps/<page_tab_id>/registration/checkin
Description
Required Scope: apps
Check-in Event Pass for Registration campaign.
Input Parameters| pass_code | 8 digit alphanumeric code. One of pass_code OR pass_uid required. |
| pass_uid | UUID. One of pass_code OR pass_uid required. |
An Event Pass object with following structure
Resulting Structure| pass_uid | |
| section_uid | |
| claim_fan_id | |
| fan_id | |
| checked_in |
GET /v1/crm/get_updates
Description
Required Scope: apps
A combined API call to get multiple arrays of updated entities as requested by the API
Input Parameters| performances | Include Performances: true/false |
| idols | Include Idols: true/false |
| idol_events | Include Idol Events: true/false |
| last_update_time | Unix time for query. must be with in 1 hour of current time |
Returns a dictionary with corresponding arrays keyed by the entity name
Resulting StructureInformational Calls
GET /v1/networks
Description
Gets a list of valid networks supported by Tradable Bits, optionally filtered by category.
Input Parameters| category | The category a network is associated with. Options are account_app, ads, auth, stream, sales, tracker, pos and crm |
An array of network objects
Resulting Structure| network | Name of the Network |
| description | Description of the Network |
| categories | Categories that are associated with the Network |
