Developers
Our platform was built to be flexible and intuitive for developers like you. You own all the data
you collect with Tradable Bits. Our API and SDK are designed to make it easy to access your fan data,
tickets and campaigns at any time, on your terms
Customize the front end of any of your campaigns with the help of our documentation, complete with
examples. Our RESTful API helps you access, send or receive fan data from our system to your
endpoints quickly and securely.
Enrich your Fan CRM and Tickets Analytics with data from other CRM systems through our many
integrations. Have any questions about our developers platform? Our support team is happy to help.
Tradable Bits Server API
NEVER EXPOSE API SECRET IN NON-SECURE ENVIRONMENT E.G. BROWSER OR MOBILE APP.
THIS KEY MUST BE KEPT SECURE ON YOUR SERVER SIDE.
You can access the majority of your CRM data through our HTTP-based API. Requests should be sent as application/x-www-form-urlencoded and will return JSON data. Authentication is managed via API Keys. The system recognises two form of keys: Public and Secret. Public is meant to be shared and can be used in insecure environments. Secret key is reserved for server-to-server communications and must be kept private. API Keys can be sent either in the request body as api_key and api_secret or as headers using Api-Key and Api-Secret. You can manage API Keys under the profile section once you log into Tradable Bits.
There is a limit to how often you can call the Tradable Bits API.
Currently, it's set to 10000 calls per minute. If you need a higher limit, please reach out to us.
This call requires api_secret as
an additional parameter.
Calls with Lock icon are meant for data exchange or called from the server side.
Each call must include api_secret as either GET or POST parameter.
This call requires api_key as
an additional parameter.
Calls with Unlock icon are meant to be integrated into mobile or web applications and require
api_key as additional parameter for all requests.
API Console
API Access allows you to query most of your Tradable Bits data, as well as register for push notification from our CRM system. Our API Reference is broken into sections by topic: Campaigns, Stream, CRM, etc.
Each Request must include api_key as parameter. You can generate an API key in the Manage Centre.You may try most of our API calls here. Your API Key will be automatically appended if available.
Segments Calls
GET /v1/segments
Description
Required Scope: segments
Supported Content Types:
- application/x-www-form-urlencoded
List available segments on the account. This endpoint will return three different types of segments: tags, snapshots, and search filters
ResultArray of Objects
Resulting Structure| segment_count | Number of fans associated with the segment. |
| segment_type | One of: tag, snapshot, or filter |
| segment_id | Unique identifier for the segment. |
| segment_name | Name of the segment. |
GET /v1/segments/<segment_type>/<segment_id>/status
Description
Required Scope: segments
Supported Content Types:
- application/x-www-form-urlencoded
Obtain the status of a given segment including metrics on the size and fans
ResultDictionary with following metrics
Resulting Structure| fan_count | Total number of fans in the segment. |
| email_count | Total number of emails in the segment. |
| phone_count | Total number of phones in the segment. |
| phone_subscribe_count | Total number of subscribed phones in the segment. |
| email_subscribe_count | Total number of subscribed emails in the segment. |
| last_update_timestamp | Timestamp of the most recent update to a fan in the segment, as unix timestamp. |
| last_update_timestamp_iso | Timestamp of the most recent update to a fan in the segment, as ISO 8601 timestamp. |
GET /v1/segments/<segment_type>/<segment_id>
Description
Required Scope: segments
Supported Content Types:
- application/x-www-form-urlencoded
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, default is 1000. |
Dictionary with meta and data elements. meta may include search_uid if output has to be paged.
Resulting Structure| fan_id | Unique identifier 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 |
| last_update_timestamp | Timestamp of most recent update to the fan, as unix timestamp. |
| last_update_timestamp_iso | Timestamp of most recent update to the fan, as ISO 8601 timestamp. |
Crm Calls
GET /v1/crm/activity_stats
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
Get a list of Engagement Campaigns and Loyalty Portal Quests on the account.
Input Parameters| q | Filter by campaign or quest name |
Array of structures
Resulting Structure| account_id | |
| app_type | |
| business_id | |
| creation_timestamp | |
| creation_timestamp_iso | |
| is_active | |
| page_tab_id | |
| timezone | |
| title |
GET /v1/crm/activities
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Download incremental list of activities for the account. Paging is implemented with help of usage of max_activity_id and min_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| account_id | Tradable Bits Account ID |
| activity_duration_ms | Time taken to complete the activity in milliseconds |
| activity_id | Unique Identifier for the activity |
| app_type | For contests - type of contest |
| campaign_title | Title of the campaign |
| creation_timestamp | Timestamp of the activity, as unix timestamp |
| creation_timestamp_iso | Timestamp of the activity, as ISO 8601 timestamp |
| details | JSON structure of campaign details (varies by campaign) |
| device_type | The type of device the fan was using at time of entry. |
| Email as submitted on the activity | |
| fan_id | Unique Identifier for the fan record |
| first_name | First name as submitted on the activity. |
| ip_address | IP Address |
| is_phone_subscribed | Opted in to SMS Marketing |
| is_subscribed | Opted in to Email Marketing |
| last_name | Last name as submitted on the activity |
| page_tab_id | ID of campaign / quest for this activity |
| phone | Phone as submitted on the activity |
| country_code | Country Code as submitted on the activity |
| province | Province as submitted on the activity |
| city | City as submitted on the activity |
| metro_area | Metro Area as submitted on the activity |
| postal_code | Postal Code as submitted on the activity |
| latitude | Latitude as submitted on the activity |
| longitude | Longitude as submitted on the activity |
| user_key | Facebook/Spotify/etc User Key |
| connection_fan_ids | List of Fan IDs connected to this fan |
| fan | Fan Structure as per documentation |
| identifiers | List of Fan Identifier structures as per documentation |
| idol_names | List of connected Idols |
| opted_in_business_ids | List of business IDs that the fan is opted in to. |
POST /v1/crm/activities
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
- application/json
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 |
Object
Resulting Structure| fan_id | |
| activity_id |
GET /v1/crm/activities/<page_tab_id>/leaderboard
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Fetch top 10 performing fans for a campaign. Leaderboard is only available for the following campaign types: Wager, Memory Match, Arcade, Trivia, and Bingo. For FanXP campaigns please use /v1/fanxp/<page_tab_id>/leaderboard
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
Supported Content Types:
- application/x-www-form-urlencoded
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 | Creation timestamp as unix timestamp |
| creation_timestamp_iso | Creation timestamp as ISO 8601 timestamp |
| first_name | |
| last_name | |
GET /v1/crm/fans
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Search for Fan records using CRM Search interface
Input Parameters| include_recent_entry | Include latest campaign into payload on result |
| include_business_opt_ins | Include business opt ins into payload on result |
| name | Email, Phone, Display Name, or Fan ID of a fan. |
| crm_active_days | |
| crm_inactive_days | |
| crm_start_active_date | |
| crm_end_active_date | |
| fan_youngest_age | |
| fan_oldest_age | |
| fan_incl_snapshot_uids | |
| fan_excl_snapshot_uids | |
| fan_tags | |
| include_tags | Include fan tags into payload on result |
| fan_tag_relations | Whether to include fans with tags related to those supplied in 'fan_tags' field |
| fan_networks | |
| fan_only_filter | List. When given, search will return results where the given values are not null (or true). Valid Options are: 'is_subscribed', 'is_optout', 'is_phone_subscribed', 'phone', 'birth_date', 'gender', 'fan_source', 'country_code', 'province', 'metro_area', 'city', 'postal_code', 'latitude' |
| fan_not_only_filter | List. When given, search will return results where the given values are null (or false). Valid Options are: 'is_subscribed', 'is_optout', 'is_phone_subscribed', 'phone', 'birth_date', 'gender', 'fan_source', 'country_code', 'province', 'metro_area', 'city', 'postal_code', 'latitude' |
| fan_postal_codes | |
| fan_radius_longitude | A valid longitude. Ex. 45.501. Must be accompanied by fan_radius_latitude and fan_radius_km. |
| fan_radius_latitude | A valid latitude. Ex. -73.57. Must be accompanied by fan_radius_longitude and fan_radius_km. |
| fan_radius_km | Must be given when supplying a single fan_postal_codes or when supplying a fan_radius_longitude and fan_radius_latitude |
| fan_provinces | |
| fan_rating | |
| fan_gender | |
| fan_source | |
| fan_metro_areas | |
| fan_start_creation_date | Format YYYY-MM-DD |
| fan_end_creation_date | Format YYYY-MM-DD |
| idol_names | |
| idol_relations | |
| ticket_event_name | |
| ticket_price_code | |
| ticket_start_purchase_date | |
| ticket_end_purchase_date | |
| ticket_venue_name | |
| ticket_venue_provinces | |
| ticket_purchased_days | |
| ticket_artist_name | |
| ticket_start_event_date | |
| ticket_end_event_date | |
| ticket_seat_price_min | |
| ticket_seat_price_max | |
| ticket_seat_count_min | |
| ticket_seat_count_max | |
| ticket_sales_count_min | |
| ticket_sales_count_max | |
| ticket_is_negative | |
| search_uid | If this parameter is supplied, we will continue returning records from previous search execution |
| limit | Maximum page size. Has to be less than a 1000 |
| max_count | Maximum total number of records retrieved. Max value of 1,000,000. Default = 100,000 |
Array with Meta structure as part of result
Resulting Structure| access_code | |
| account_id | |
| birth_date | |
| city | |
| country_code | |
| creation_timestamp | |
| creation_timestamp_iso | |
| display_name | |
| fan_id | |
| fan_source | |
| fields | |
| first_name | |
| gender | |
| has_password | |
| ip_address | |
| is_confirmed | |
| is_guest | |
| is_optout | |
| is_phone_confirmed | |
| is_phone_subscribed | |
| is_subscribed | |
| last_campaign_name | |
| last_name | |
| last_page_tab_id | |
| last_update_timestamp | |
| last_update_timestamp_iso | |
| latitude | |
| longitude | |
| metro_area | |
| moderator_status | |
| name | |
| opted_in_business_ids | |
| phone | |
| postal_code | |
| props | |
| province | |
| rating | |
| tags |
GET /v1/crm/fan_identifiers
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Get fan identifiers for all fans in the account
Input Parameters| network * | Required. |
| identifier_value | Optional. Search by the value of the identifier, e.g. email@gmail.com, +1234567890 (exact match) |
| limit | Optional. Specify the maximum amount of fan identifiers returned, defaults to 1000 |
A list of fan identifiers
Resulting Structure| account_id | |
| fan_id | |
| network | |
| identifier_value | |
| creation_timestamp | |
| creation_timestamp_iso |
GET /v1/crm/fan_updates
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| customer_dsn | Identifies the tickets source |
| network | type of remote network to fetch ticket |
| event_key | Event Key in remote system |
| event_date | ISO date of the event |
| event_name | Event Name |
| purchase_timestamp | ISO Date |
| paid_amount | Total Paid Amount |
| order_amount | Full Order Amount |
| barcode | Wristband Barcode |
| lookup_id | Wristband Lookup ID |
| num_seats | Number of tickets/seats on the purchase |
| fan_id | Unique Fan Identifier |
| artist_name | Artist Name |
| price_code | Price Code or Level |
| venue_name | Name of Venue |
| city | City |
| province | Province or State |
| country_code | ISO country code |
| metro_area | DMA or CMA Area (Currently only for US/CA) |
| venue_province | Province or State of Venue |
| order_key | Identifier for the Order |
| ticket_category | Ticket Category |
| import_uid | Identifies the ticket import (if applicable) |
| postal_code | Postal Code / ZIP |
| customer_key | ID of customer in remote system |
| is_deleted | True if ticket deleted |
| ticket_type | Ticket Type |
| ticket_type_category | Category of Ticket Type |
| last_update_timestamp | Timestamp of last update in ISO 8601 format |
| original_paid_amount | Full paid ticket amount before discounts or fees |
| original_order_amount | Full order amount before discounts or fees |
| original_num_seats | Original number of seats |
| status | Ticket Status |
| fan | Fan reference |
| section_name | Ticket Section Name |
| row_name | Ticket Row Name |
| seat_num | Ticket Seat Number |
| plan_event_key | Plan Event Name |
GET /v1/crm/tickets/<ticket_id>
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| customer_dsn | Identifies the tickets source |
| network | type of remote network to fetch ticket |
| event_key | Event Key in remote system |
| event_date | ISO date of the event |
| event_name | Event Name |
| purchase_timestamp | ISO Date |
| paid_amount | Total Paid Amount |
| order_amount | Full Order Amount |
| barcode | Wristband Barcode |
| lookup_id | Wristband Lookup ID |
| num_seats | Number of tickets/seats on the purchase |
| fan_id | Unique Fan Identifier |
| artist_name | Artist Name |
| price_code | Price Code or Level |
| venue_name | Name of Venue |
| city | City |
| province | Province or State |
| country_code | ISO country code |
| metro_area | DMA or CMA Area (Currently only for US/CA) |
| venue_province | Province or State of Venue |
| order_key | Identifier for the Order |
| ticket_category | Ticket Category |
| import_uid | Identifies the ticket import (if applicable) |
| postal_code | Postal Code / ZIP |
| customer_key | ID of customer in remote system |
| is_deleted | True if ticket deleted |
| ticket_type | Ticket Type |
| ticket_type_category | Category of Ticket Type |
| last_update_timestamp | Timestamp of last update in ISO 8601 format |
| creation_timestamp | Creation timestamp in ISO 8601 format |
| original_paid_amount | Full paid ticket amount before discounts or fees |
| original_order_amount | Full order amount before discounts or fees |
| original_num_seats | Original number of seats |
| original_num_seats | Original number of seats |
| status | Ticket Status |
| fan | Fan reference |
| section_name | Ticket Section Name |
| row_name | Ticket Row Name |
| seat_num | Ticket Seat Number |
| plan_event_key | Plan Event Name |
POST /v1/crm/tickets
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
- application/json
Create new Ticket and corresponding Fan record
Input Parameters| first_name * | String of the fans first name |
| last_name * | String of the fans last name |
| email * | String of the fans email address |
| purchase_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| paid_amount * | Numeric value for line item |
| num_seats * | Integer number of seats purchased |
| event_date * | ISO8601 Encoded String |
| event_name * | String of the event name |
| phone | String of the fans phone number |
| customer_key | Key of the customer in the remote system |
| ticket_key | Optional. Unique identifier for the line item (i.e. unique per price code and amount). |
| price_code | Optional. Price level or code of line item |
| is_subscribed | Boolean of the fan's email subscribe status |
| is_phone_subscribed | Boolean of the fans phone subscribe status |
| city | String of the fans city |
| province | String of the fans province |
| postal_code | String of the fans postal code |
| country_code | String of the fans country code |
| artist_name | String of the artist name |
| venue_name | String of the venue name |
| venue_province | String of the venue province |
| venue_country_code | String of the venue country code |
| event_key | String of the event key |
| network | String of the network |
| order_key | String of the order key |
| is_deleted | Boolean value |
| fan_source | Text identifier if fan is to be created |
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
Supported Content Types:
- application/json
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
Supported Content Types:
- application/x-www-form-urlencoded
- application/json
Get ticket events, with optional filtering 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 | |
| customer_dsn | |
| event_price | |
| performance_uid | |
| performance_name | |
| is_edited | |
| is_excluded | |
| apply_historical | |
| campaign_event_key | |
| is_placeholder | |
| short_event_name | |
| creation_timestamp_iso |
POST /v1/crm/tickets/events
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
| registration_timestamp_iso | Timestamp of registration. ISO 8601 format |
| email on the ticket | |
| venue_name | |
| barcode | |
| lookup_id | |
| ticket_key | |
| network | |
| first_name | |
| last_name | |
| phone | |
| address | |
| city | |
| country_code | |
| province | |
| postal_code | |
| is_minor | |
| birth_date | |
| is_preferred | |
| creation_timestamp | Timestamp of import. Unix Time |
| creation_timestamp_iso | Timestamp of import. ISO 8601 format |
| activity_id | |
| is_subscribed | |
| is_phone_subscribed | |
| performance_uid | Performance UUID of the ticket event associated with the registration |
POST /v1/crm/registrations
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
Get registration and scan data by scan_group_name. Results are ordered by scan_key ascending.
Input Parameters| scan_group_name * | String. Identifier for different groups of scans. One of scan_group_name or scan_group_name_prefix is required. |
| scan_group_name_prefix | String. Perform prefix matching on scan_group_name. i.e. scan_group_name_prefix=abc will do a case-insensitive prefix search and return all rows that start with 'abc', 'ABC', etc. One of scan_group_name or scan_group_name_prefix is required. |
| start_date * | Scan creation start_date, scans between start_date and end_date will be fetched. |
| end_date * | Scan creation end_date, scans between start_date and end_date will be fetched |
| network * | The ticketing network. |
| next_scan_key | Used for pagination, each response will contain a 'next_scan_key' value which is to be supplied in the subsequent request in order to page through all records in the response. It does not need to be supplied on the first request to this endpoint. |
| venue_name | Venue name for the event. |
| event_date | Date of the event. |
Scan 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. |
| fgt_site_name | Site name associated with this scan. |
| fgt_site_id | The integer ID for the site. |
| fgt_zone_name | |
| scan_timestamp | The time that scan occurred |
| registration_key | The registration key. |
| order_key | The order key of the associated ticket. |
| ticket_key | The ticket key of the associated ticket. |
| pii_source | Can be one of: 'ticket' or 'registration' |
| event_name | The name of the event linked to the registration |
| event_date | The date of the event linked to the registration. |
| venue_name | Venue name linked to the registration |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
- application/json
Create new Fan record
Input Parameters| first_name | Max length 255 characters |
| last_name | Max length 255 characters |
| name | Max length 255 characters. If name is provided, the first and last name arguments will not be used. |
| 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. |
| tag_<tag_name> | Send tag_<tag_name> as a field with true/false/on/off as the value. If true, then the tag will be added to the fan, else the tag will be removed from the fan. |
| field_<crm_field_key> | Send field_<crm_field_key> as a field with some value i.e. field_my_key=helloworld. This will set the value of a custom field named 'my_key' to 'helloworld' on the fan. |
| fan_source | Text identifier if fan is to be created |
| is_optout | |
| idol_names | Array of idol names to associate as fan idols |
Created Record
Resulting Structure| fan_id |
POST /v1/crm/idol_fans
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
Get fan identifiers for a specific Fan ID
Input Parameters| network | Optional. |
| identifier_value | Optional. Search by the value of the identifier, e.g. email@gmail.com, +1234567890 (exact match). |
A 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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
Get Specific fan record via ID
ResultFollowing structure
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| display_name | |
| is_confirmed | |
| is_phone_confirmed | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_optout | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| last_update_timestamp | |
| fan_source | |
| fields | |
| gender | |
| tags | |
| moderator_status | |
| access_code | |
| has_password | |
| props | |
| is_guest | |
| last_page_tab_id | |
| last_campaign_name | |
| opted_in_business_ids | |
| creation_timestamp_iso | |
| last_update_timestamp_iso | |
| connected_fans | |
| identifiers |
POST /v1/crm/fans/<fan_id>
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
Delete Fan record
ResultBoolean value of True
GET /v1/crm/fans/<fan_id>/points
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Get Fan points
Input Parameters| page_tab_id | ID of campaign or quest |
Following structure
Resulting Structure| fan_point_uid | |
| fan_id | |
| point_uid | |
| point_name | |
| point_count | |
| point_source | |
| creation_timestamp | Creation timestamp in ISO8601 format |
POST /v1/crm/fans/<fan_id>/points
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Award points to a Fan
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
| registration_timestamp_iso | Timestamp of registration. ISO 8601 format |
| email on the ticket | |
| venue_name | |
| barcode | |
| lookup_id | |
| ticket_key | |
| network | |
| first_name | |
| last_name | |
| phone | |
| address | |
| city | |
| country_code | |
| province | |
| postal_code | |
| is_minor | |
| birth_date | |
| is_preferred | |
| creation_timestamp | Timestamp of import. Unix Time |
| creation_timestamp_iso | Timestamp of import. ISO 8601 format |
| activity_id | |
| is_subscribed | |
| is_phone_subscribed | |
| performance_uid | Performance UUID of the ticket event associated with the registration if it exists |
POST /v1/crm/fans/<fan_id>/registrations
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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| fan_id | |
| campaign_title | |
| creation_timestamp | Creation timestamp as Unix timestamp |
| creation_timestamp_iso | Creation timestamp in ISO 8601 format |
| props |
POST /v1/crm/fans/<fan_id>/activities
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Create new Activity record for a given Fan
Input Parameters| campaign_title * | Name of custom campaign |
| field_<custom field name> | 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
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| link_url | |
| usage_count | |
| creation_timestamp_iso |
GET /v1/crm/search_filters
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
GET /v1/crm/fan_connections/<int:fan_id>
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Returns the connections for a given fan
Input Parameters| limit | Optional limit on the amount of connections to return, will search for last updated fans in descending order. If not included will return all connections for the fan. |
A FanConnections object
Resulting Structure| total_count | The total connections for the given fan, affected by the limit clause if included. |
| pending_approval_count | The number of connections that have not been approved yet, affected by the limit clause if included. |
| connections | A list of fan connections, affected by the limit clause if included. |
POST /v1/crm/fan_connections/<int:fan_id>
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Creates a pending fan connection for the fan and connected_fan respectively. Once a request has been created, it can be approved or declined through the /v1/crm/fan_connections/requests/<int:fan_id> endpoint
Input Parameters| connected_fan_id * | The fan_id of the fan you want to associate the connection with |
A successful confirmation message
Resulting Structure| message | If the call is successful a message will be returned confirming the connection status between specified fans. |
POST /v1/crm/fan_connections/requests/<int:fan_id>
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
Accepts or declines a pending fan connection
Input Parameters| connected_fan_id * | The fan_id of the fan you want to associate the connection with |
| is_approved | Whether to accept or decline the pending friend request. If not included will default to declining. |
A successful confirmation message
Resulting Structure| message | If the call is successful a message will be returned confirming the connection status between specified fans. |
Ent Calls
GET /v1/ent/performances
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| creation_timestamp_iso | Creation timestamp in ISO 8601 format |
| onsale_date | |
| venue_name | |
| display_venue_name | |
| promoter | |
| artist_name | |
| additional_artist_names | |
| campaign_event_key | |
| campaign_tour_key | |
| media_uid | |
| connected_ticket_events | List of connected ticket event names |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
Create a new performance. Take note that this endpoint does not require a secret key unlike other endpoints for performances.
Input Parameters| performance_name * | Maximum length of 255 characters |
| 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 | Maximum length of 128 characters |
| artist_name | Maximum length of 255 characters |
| campaign_event_key | Maximum length of 64 characters |
| campaign_tour_key | Maximum length of 64 characters |
| performance_url | Must begin with https://. Maximum length of 512 characters. |
| status | draft, ready, or archived |
| buying_group | |
| notes | |
| performance_group_name | Maximum length of 128 characters |
| business_id | |
| fb_event_id | |
| label_name | |
| additional_artist_names | List of strings, each string has a maximum length of 256 characters |
| outlet | Maximum length of 128 characters |
| vendor | Maximum length of 128 characters |
| referral_page_tab_id |
New performance record
Resulting Structure| performance_uid | Identifier for performance |
GET /v1/ent/performances/<performance_uid>
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| creation_timestamp_iso | |
| media_uid | |
| connected_ticket_events | |
| campaign_tour_key | |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
Update performance
Input Parameters| performance_name * | Maximum length of 255 characters |
| 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 | Maximum length of 128 characters |
| artist_name | Maximum length of 255 characters |
| campaign_event_key | Maximum length of 64 characters |
| campaign_tour_key | Maximum length of 64 characters |
| performance_url | Must begin with https://, maximum length of 512 characters |
| status | draft, ready, or archived |
| buying_group | |
| notes | |
| performance_group_name | Maximum length of 128 characters |
| fb_event_id | |
| label_name | |
| additional_artist_names | List of strings, each string has a maximum length of 256 characters |
| outlet | Maximum length of 128 characters |
| vendor | Maximum length of 128 characters |
| referral_page_tab_id |
Updated performance record
Resulting Structure| performance_uid | Identifier for performance |
DELETE /v1/ent/performances/<performance_uid>
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
Delete performance
ResultBoolean value of True
GET /v1/ent/businesses/<business_id>/quests
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
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 | Max length 128 |
| button_text | Max length 32 |
| quest_description | |
| reward_type | |
| fan_points_reward | |
| atvenu_sales_event_key | |
| atvenu_promo_key | |
| atvenu_delivery_method | |
| creation_timestamp | |
| bestring_location_group_id | |
| bestring_promotion_id | |
| required_page_tab_ids | |
| link_url | |
| start_date | |
| end_date | |
| site_name | Required when quest_type is 'scan'. |
| scan_min_timestamp | For scan quests, and only when min and max are present, scans will only count as a completion if after this timestamp |
| scan_max_timestamp | For scan quests, and only when min and max are present, scans will only count as a completion if before this timestamp |
| point_tier_uid | |
| quiz_questions | Relevant for 'quickpicks' type quests only. |
| idol_uid | Associated idol (artist or sponsor) |
| disable_atvenu_qrcode_email | Boolean. Emails are not sent after reward achieved for Atvenu reward with qrcode set as the atvenu_delivery_method |
| business_id | |
| order_idx | |
| status | |
| status_message |
POST /v1/ent/businesses/<business_id>/quests
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Create a quest
Input Parameters| quest_title * | |
| quest_type * | Must be one of 'scan', 'campaign', 'quickpicks', 'wristband', 'link_url', or 'custom' |
| performance_uid | Used to assign quest to a performance. Required when quest_type is 'scan' or 'wristband', and when the reward_type is 'atvenu' or 'bestring', otherwise optional. |
| is_required | |
| target_page_tab_id | Required if quest_type is 'campaign' or 'quickpicks', for 'quickpicks' the target_page_tab_id must be a Quickpicks campaign. |
| site_name | Required if quest_type is 'scan' |
| scan_group_names[] | Required if quest_type is 'scan' |
| link_url | Required if quest_type is 'link_url' |
| access_restriction_type | Optional. Must be one of 'quests', 'fan_points', or 'point_tier'. |
| fan_points_required | Required when access_restriction_type is 'fan_points' |
| point_tier_uid | Required when access_restriction_type is 'point_tier', point_tier_uid of a valid point tier. |
| required_page_tab_ids | Required when access_restriction_type is 'quests'. Provide each value as a separate required_page_tab_ids=<int:value> in the request body. |
| reward_type | Optional. If included, must be one of 'atvenu', 'fan_points', 'bestring' |
| bestring_location_group_id | Required if reward_type is 'bestring', otherwise ignored |
| bestring_promotion_id | Required if reward_type is 'bestring', otherwise ignored |
| atvenu_sales_event_key | Required if reward_type is 'atvenu', otherwise ignored |
| atvenu_promo_key | Required if reward_type is 'atvenu', otherwise ignored |
| atvenu_delivery_method | Required if reward_type is 'atvenu', otherwise ignored. Either 'wristband' or 'qrcode'. |
| disable_atvenu_qrcode_email | Optional boolean, defaults to false. If 'atvenu' reward type is used with 'qrcode' set as the atvenu_delivery_method, enables/disables sending an email to the fan when they receive the reward. |
| fan_points_reward | Required if reward_type is 'fan_points', otherwise ignored |
| button_text | |
| quest_description | |
| start_date | |
| end_date | |
| scan_min_timestamp | For scan quests, and only when min and max are present, scans will only count as a completion if after this timestamp |
| scan_max_timestamp | For scan quests, and only when min and max are present, scans will only count as a completion if before this timestamp |
| idol_uid | Associated idol (artist or sponsor). See 'GET /v1/idols/<idol_uid>' for idol details. |
ID of entity created
Resulting Structure| page_tab_id |
DELETE /v1/ent/businesses/<business_id>/quests/<page_tab_id>
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Delete quest
ResultHTTP 200
GET /v1/ent/businesses/<business_id>/rewards
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| atvenu_delivery_method | |
| fan_points_required | |
| creation_timestamp | |
| bestring_location_group_id | |
| bestring_promotion_id | |
| point_tier_uid | |
| requirement_type | |
| media_uid | |
| idol_uid | |
| description | |
| expiration_timestamp | Optional expiration timestamp of reward. Fans will no longer be awarded this after it expires. Must also set timezone. |
| timezone | Required if using expiration timestamp. Format ex. 'America/Vancouver'. |
| disable_atvenu_qrcode_email | Boolean. Emails are not sent after reward achieved for Atvenu reward with qrcode set as the atvenu_delivery_method |
| required_page_tab_ids | |
| point_uid |
POST /v1/ent/businesses/<business_id>/rewards
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Create a reward
Input Parameters| reward_title * | |
| reward_type * | 'atvenu', 'bestring', or 'badge'. If 'badge' reward type is used then no atVenu/Bestring parameters should be passed. |
| requirement_type * | Describes the type of requirement for the reward. Value must be 'fan_points', 'point_tier', or 'quests'. |
| fan_points_required | Required when access_restriction_type is 'fan_points' |
| point_tier_uid | Required when access_restriction_type is 'point_tier' |
| required_page_tab_ids | Required when access_restriction_type is 'quests'. Provide each value as a separate required_page_tab_ids=<int:value> in the request body. |
| 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 | |
| idol_uid | Optional associated idol. See /idols for details. |
| atvenu_delivery_method | Required when reward_type is 'atvenu'. Either 'wristband' or 'qrcode'. |
| disable_atvenu_qrcode_email | Boolean. Emails are not sent after reward achieved for Atvenu reward with qrcode set as the atvenu_delivery_method |
| description | Optional description of the reward. |
| expiration_timestamp | Optionally set expiration of reward. Fans will no longer be awarded this after it expires. Must also set timezone. |
| timezone | Required if using expiration timestamp. Format ex. 'America/Vancouver'. |
ID of entity created.
Resulting Structure| reward_uid |
DELETE /v1/ent/businesses/<business_id>/rewards/<reward_uid>
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Delete a reward
ResultHTTP 200
GET /v1/ent/businesses/<business_id>/fans/<fan_id>/rewards
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Get all rewards won by a given fan.
Input Parameters| performance_uid | Optionally filter by performance. |
An array of reward objects
Resulting Structure| reward_uid | Reward object identifier |
| business_id | Associated business |
| performance_uid | Associated performance |
| reward_title | |
| reward_type | 'atvenu', 'bestring', or 'badge' |
| atvenu_sales_event_key | |
| atvenu_promo_key | |
| atvenu_delivery_method | |
| fan_points_required | |
| creation_timestamp | Creation time of reward object |
| bestring_location_group_id | |
| bestring_promotion_id | |
| point_tier_uid | Available if requirement_type is 'point_tier' |
| requirement_type | One of 'point_tier', 'fan_point', 'quests |
| media_uid | |
| idol_uid | |
| description | |
| expiration_timestamp | Optional expiration timestamp of reward. Fans will no longer be awarded this after it expires. Must also set timezone. |
| timezone | Required if using expiration timestamp. Format ex. 'America/Vancouver'. |
| disable_atvenu_qrcode_email | Boolean. Emails are not sent after reward achieved for Atvenu reward with qrcode set as the atvenu_delivery_method |
| required_page_tab_ids | Array of quest page_tab_ids if requirement_type is 'quests |
| fan_point_uid | Identifier of fan point associated with the reward. Also the QR code data when atvenu_delivery_method is set to 'qrcode'. |
GET /v1/ent/fans/<fan_id>/events
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
| states | Array of states for the idol event fan. Minimum 1, maximum 4. Valid states are 'saved', 'going', 'verified', 'attended', or 'collected'. Defaults to ['saved']. |
Following structure
Resulting Structure| fan_id | |
| idol_event_uid | |
| states | Array of states for the idol event fan. Minimum 1, maximum 4. Valid states are 'saved', 'going', 'verified', 'attended', or 'collected'. Defaults to ['saved']. |
DELETE /v1/ent/fans/<fan_id>/idols/events
Description
Required Scope: crm
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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.
POST /v1/ent/fans/<fan_id>/member_id
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Generate a member_id for the given fan. The member_id will also be created as a fan identifier with network = 'festiverse'. Attempting to create a member_id for a fan who already has a member_id will result in an error.
ResultThe generated member_id for the given fan.
Resulting Structure| fan_id | Integer. The fan_id passed into the request. |
| member_id | String. The member_id generated for this fan. |
Streams Calls
GET /v1/streams
Description
Required Scope: streams
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| tag_id | |
| tag_name | |
| authorized_networks | |
| creation_timestamp_iso |
GET /v1/streams/<stream_key>/records
Description
Required Scope: streams
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| link_uid | |
| link_level | |
| width | |
| height | |
| record_media_uid | |
| video_media_uid | |
| profile_url | |
| display_name | |
| is_approved | |
| is_granted | |
| is_reviewed | |
| is_reported | |
| is_permanent | |
| hashtags | |
| like_count | |
| access_counter | |
| labels | |
| label_timestamp | |
| time_key | |
| follows |
POST /v1/streams/<stream_key>/records
Description
Required Scope: streams
Supported Content Types:
- application/x-www-form-urlencoded
Create new Stream Record
Input Parameters| email * | |
| name | Name is required if email does not exist |
| fan_id | Use an existing fan's name/email for the record, will default to name/email parameters if the fan does not exist |
| image_url | |
| caption | |
| latitude | |
| longitude | |
| labels | Comma separated list of labels |
| props_<prop_name> | 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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
Sessions Calls
POST /v1/sessions/wifi_fans
Description
Required Scope: sessions
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
Get existing Session using ID
ResultRecord
Resulting Structure| session_uid | |
| fan_id | |
| account_id | |
| props | |
| expiration_timestamp | |
| expiration_timestamp_iso | |
| creation_timestamp | |
| creation_timestamp_iso | |
| user_key | |
| network | |
| page_tab_id | |
| business_id | |
| ip_address | |
| login_type | |
| login_source | |
| tag_ids |
GET /v1/sessions/<session_uid>/fan
Description
Required Scope: sessions
Supported Content Types:
- application/x-www-form-urlencoded
Fetch current Fan Record
ResultFollowing Structure
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| display_name | |
| is_confirmed | |
| is_phone_confirmed | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_optout | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| last_update_timestamp | |
| fan_source | |
| fields | |
| gender | |
| tags | |
| moderator_status | |
| access_code | |
| has_password | |
| props | |
| is_guest | |
| last_page_tab_id | |
| last_campaign_name | |
| opted_in_business_ids | |
| creation_timestamp_iso | |
| last_update_timestamp_iso |
POST /v1/sessions/<session_uid>/fan
Description
Required Scope: sessions
Supported Content Types:
- application/x-www-form-urlencoded
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_<prop_name> | update props |
| field_<crm_field_key> | update fields |
| tag_<crm_tag_id> | update tags |
Updated Record
Resulting Structure| fan_id |
GET /v1/sessions/<session_uid>/points
Description
Required Scope: sessions
Supported Content Types:
- application/x-www-form-urlencoded
Get Fan points
ResultFollowing structure
Resulting Structure| fan_id | |
| point_uid | |
| point_name | |
| point_count | |
| fan_point_uid | |
| point_source |
Idols Calls
POST /v1/idols
Description
Required Scope: idols
Supported Content Types:
- application/x-www-form-urlencoded
Create new idol in the database
Input Parameters| idol_name * | Name of the new idol. Max length 255 |
| 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. Max length 128 |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| link_url | |
| idol_type | |
| idol_labels | An array of labels associated with this idol. |
| artist_name | |
| props | |
| creation_timestamp | |
| creation_timestamp_iso |
GET /v1/idols/<idol_uid>
Description
Required Scope: idols
Supported Content Types:
- application/x-www-form-urlencoded
Obtain an idol for a given idol_uid
ResultA structure for a given idol as follows
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| 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. |
| artist_name | |
| creation_timestamp | |
| creation_timestamp_iso |
GET /v1/idols/events
Description
Required Scope: idols
Supported Content Types:
- application/x-www-form-urlencoded
Based on the search parameters return a list of Idol Events.
Input Parameters| idol_uid | If specified, only events with a matching idol_uid will returned |
| performance_uid | Used to fetch Idol Events associated with a specific Performance |
| venue_name | If specified, only events with a matching venue_name will returned |
| q | If specified, only events with a venue_name or idol_name like the parameter will returned |
| label_name | If specified, only events with a matching label_name will returned |
| start_date | If specified, only events starting after this date will returned. Will return an error if display_date is also supplied |
| end_date | If specified, only events ending before this date will returned. Will return an error if display_date is also supplied |
| display_date | Search by the assigned display date of the event. Will return an error if start_date or end_date are also supplied |
Array of JSON records matching the search
Resulting Structure| idol_event_uid | |
| account_id | |
| idol_uid | |
| start_timestamp | |
| end_timestamp | |
| venue_name | |
| display_venue_name | Venue name which is suitable to display in UI. Can contain HTML and special characters. |
| 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 | |
| last_update_timestamp_iso | |
| 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) |
| event_name | |
| start_date | |
| end_date | |
| start_time | |
| end_time | |
| creation_timestamp | |
| creation_timestamp_iso |
Reports Calls
GET /v1/reports
Description
Required Scope: reports
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
Misc Calls
GET /v1/trackers
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
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/qrcode
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
Get a QR Code image encoding the given 'code' parameter
Input Parameters| code * | The code that should be encoded in the returned QR image |
| front_color | Colour of the pixelated part of QR code image. Default black. |
| back_color | Backing colour or QR code image. Default white. |
| size | Pixel size of QR code image. Default 400px, Max 5000px. |
QR Code image
GET /v1/trackers/<tracker_id>
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
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
ResultThe 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
Supported Content Types:
- application/x-www-form-urlencoded
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. |
| venue_id_wildcard | Venue ID 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
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| tracker_click_uid | |
| account_id | |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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| country_code | |
| province | |
| metro_area | |
| city | |
| latitude | |
| longitude | |
| country_name | |
| postal_code |
POST /v1/yinzcam_subscription
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
- application/json
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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
| budget_amount | |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
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 | Ad Account ID/Key |
| campaign_key | Campaign ID/Key |
| campaign_name | Campaign name |
| budget_amount | Sum of budget lines |
| spend | Total spend amount |
| impressions | Total number of impressions |
| clicks | Total number of clicks |
| link_clicks | Total number of link clicks |
| conversion_amount | Total sales value |
| conversion_count | Total number of sales |
| offline_conversion_amount | Total sales value from offline conversions |
| offline_conversion_count | Total number of offline conversions |
| custom_conversion_count | Total number of custom conversions |
| custom_conversion_amount | Total sales value from custom conversions |
| custom_offline_conversion_count | Total number of custom offline conversions |
| custom_offline_conversion_amount | Total sales value from custom offline conversions |
| roas | Total return on ad spend |
| cpc | Total cost per click |
| cpm | Total cost per thousand impressions |
GET /v1/template_portals
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
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 |
| notification_emails | |
| password_exists | |
| creation_timestamp | |
| creation_timestamp_iso | |
| last_access_timestamp | |
| last_access_timestamp_iso |
GET /v1/template_portals/<portal_uid>
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
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 |
| notification_emails | |
| password_exists | |
| creation_timestamp | |
| creation_timestamp_iso | |
| last_access_timestamp | |
| last_access_timestamp_iso |
POST /v1/template_portals
Description
Required Scope: misc
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
Delete template portal
ResultBoolean value of True
Apps Calls
GET /v1/fanxp/<page_tab_id>/leaderboard
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Get a Public Leaderboard for FanXP campaigns. For other campaign types use /v1/crm/activities/<page_tab_id>/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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 |
GET /v1/businesses/<business_id>
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| wifi_props |
GET /v1/apps/<page_tab_id>/bundle_stats
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| views | |
| geo_stats | |
| 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/fanxp/<page_tab_id>/detailed_stats
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Fetch detailed stats for a campaign. Only supports FanXP and LiveXP.
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 | Filter by start timestamp. Format YYYY-MM-DDTHH:MM:SS. |
| end_timestamp | Filter by end timestamp. Format YYYY-MM-DDTHH:MM:SS. |
| 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
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Resulting Structure| page_tab_id | |
| name | |
| props | |
| style_props | |
| time_zone | |
| is_scheduled | |
| live_status | |
| is_active | |
| privacy | |
| terms | |
| rules | |
| locale_props | |
| tab_items | |
| links_map | |
| start_timestamp | |
| end_timestamp | |
| media_map | |
| crm_fields | |
| fb_app_key |
GET /v1/apps/<page_tab_id>/total_points
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Fetch total fan points for a campaign
Input Parameters| start_timestamp | Filter by start timestamp. Format YYYY-MM-DDTHH:MM:SS |
| end_timestamp | Filter by end timestamp. Format YYYY-MM-DDTHH:MM:SS |
A structure with following fields
Resulting Structure| total_points |
GET /v1/apps/<page_tab_id>/wager_entries
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
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 | |
| position | |
| active_date | |
| props | |
| inventory_count | |
| activation_timestamp | |
| media_map | |
| wagers | |
| wager_match_id | |
| active_time | |
| end_timestamp | |
| end_date | |
| end_time | |
| is_future | |
| winner_wager_count | |
| loser_wager_count | |
| pending_wager_count | |
| fan_wager_count | |
| debit_point_count | |
| credit_point_count | |
| wager_result_count | |
| total_wager_count | |
| classic_wager_count | |
| activation_timestamp_iso | |
| end_timestamp_iso |
GET /v1/apps/<page_tab_id>/simple_points
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Fetch fan points for a campaign without any PII
Input Parameters| start_timestamp | Filter by start timestamp. Format YYYY-MM-DDTHH:MM:SS |
| end_timestamp | Filter by start timestamp. Format YYYY-MM-DDTHH:MM:SS |
A structure with following fields
Resulting Structure| fan_id | |
| point_count | |
| creation_timestamp | |
| creation_timestamp_iso |
GET /v1/apps/<page_tab_id>/simple_activities
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
Fetch fan activities for a campaign without any PII
ResultA structure with following fields
Resulting Structure| account_id | |
| page_tab_id | |
| fan_id | |
| activity_id | |
| creation_timestamp | |
| creation_timestamp_iso |
POST /v1/apps/<page_tab_id>/registration/checkin
Description
Required Scope: apps
Supported Content Types:
- application/x-www-form-urlencoded
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
Supported Content Types:
- application/x-www-form-urlencoded
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
Informational Calls
GET /v1/networks
Description
Supported Content Types:
- application/x-www-form-urlencoded
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 |
