Developers
Our platform was built to be flexible and intuitive for developers like you. You own all the data
you collect with Tradable Bits. Our API and SDK are designed to make it easy to access your fan data,
tickets and campaigns at any time, on your terms
Customize the front end of any of your campaigns with the help of our documentation, complete with
examples. Our RESTful API helps you access, send or receive fan data from our system to your
endpoints quickly and securely.
Enrich your Fan CRM and Tickets Analytics with data from other CRM systems through our many
integrations. Have any questions about our developers platform? Our support team is happy to help.
Tradable Bits Server API
NEVER EXPOSE API SECRET IN NON SECURE ENVIRONMENT E.G. BROWSER OR MOBILE APP.
THIS KEY MUST BE KEPT SECURE ON YOUR SERVER SIDE.
Most of CRM Data can be accessed with our HTTP based API. Calls should be sent as application/x-www-form-urlencoded and will return JSON data. Authentication is handled using API Keys. The system recognises two form of keys: Public and Secret. Public is meant to be shared and can be used in insecure environments whereas Secret key is reserved for server-to-server communications and must be kept private. Api keys can be sent either in the request body as api_key and api_secret or as headers using Api-Key and Api-Secret. You can manage key under profile section once you log into Tradable Bits.
There is a limit to how often you can call Tradable Bits. Currently, it's set to
600 calls per minute. If you need a higher limit, please reach out to us.
This Call Requires api_secret as
additional parameter
Calls with Lock icon are meant for data exchange or called from the server side.
Each call must include api_secret as either GET or POST parameter
This Call Requires api_key as
additional parameter
Calls with UnLock icon are meant to be integrated into mobile or web applications and require
api_key as additional parameter for all requests
Introduction
Console
Segments
GET /v1/segments
GET /v1/segments/<segment_type>/<segment_id>/status
GET /v1/segments/<segment_type>/<segment_id>
Crm
GET /v1/crm/activity_stats
GET /v1/crm/campaigns
GET /v1/crm/activities
POST /v1/crm/activities
GET /v1/crm/activities/<page_tab_id>/leaderboard
GET /v1/crm/fan_tags
GET /v1/crm/fans
GET /v1/crm/fan_updates
GET /v1/crm/fan_points
POST /v1/crm/fan_points
GET /v1/crm/points
POST /v1/crm/purchases
GET /v1/crm/purchases
GET /v1/crm/tickets
GET /v1/crm/tickets/<ticket_id>
POST /v1/crm/tickets
POST /v1/crm/bulk_tickets
GET /v1/crm/tickets/events
POST /v1/crm/tickets/events
GET /v1/crm/ticket_stats
GET /v1/crm/registrations
POST /v1/crm/registrations
GET /v1/crm/registrations/scans
POST /v1/crm/fans
GET /v1/crm/fans/<fan_id>/identifiers
GET /v1/crm/fans/<fan_id>
POST /v1/crm/fans/<fan_id>
DELETE /v1/crm/fans/<fan_id>
GET /v1/crm/fans/<fan_id>/points
POST /v1/crm/fans/<fan_id>/points
GET /v1/crm/fans/<fan_id>/idols
POST /v1/crm/fans/<fan_id>/idols
GET /v1/crm/fans/<fan_id>/registrations
POST /v1/crm/fans/<fan_id>/registrations
GET /v1/crm/fans/<fan_id>/activities
POST /v1/crm/fans/<fan_id>/activities
GET /v1/crm/fields
GET /v1/crm/search_filters
GET /v1/crm/fan_stats
GET /v1/crm/monitored_ip_addresses
POST /v1/crm/monitored_ip_addresses
DELETE /v1/crm/monitored_ip_addresses
Streams
GET /v1/streams
GET /v1/streams/<stream_key>/records
POST /v1/streams/<stream_key>/records
GET /v1/streams/<stream_key>
GET /v1/streams/<stream_key>/<feed_record_id>
POST /v1/streams/<stream_key>/<feed_record_id>
Sessions
POST /v1/sessions/wifi_fans
POST /v1/sessions/check
POST /v1/sessions/signup
POST /v1/sessions/connect
GET /v1/sessions/<session_uid>
GET /v1/sessions/<session_uid>/fan
POST /v1/sessions/<session_uid>/fan
GET /v1/sessions/<session_uid>/points
Misc
GET /v1/trackers
GET /v1/trackers/<tracker_id>
POST /v1/trackers
GET /v1/trackers/sales_pixel
GET /v1/props/<prop_name>
GET /v1/geoip
GET /v1/shp_lookup
POST /v1/yinzcam_subscription
GET /v1/account_ad_stats
GET /v1/account_ad_stats_by_campaign
GET /v1/performances
GET /v1/performances/<performance_uid>
POST /v1/performances
POST /v1/performances/<performance_uid>
DELETE /v1/performances/<performance_uid>
GET /v1/template_portals
GET /v1/template_portals/<portal_uid>
POST /v1/template_portals
POST /v1/template_portals/<portal_uid>
DELETE /v1/template_portals/<portal_uid>
Apps
GET /v1/apps/<page_tab_id>/leaderboard
GET /v1/apps
GET /v1/businesses
GET /v1/businesses/<business_id>
GET /v1/apps/<page_tab_id>/bundle_stats
GET /v1/apps/<page_tab_id>/stats
GET /v1/apps/<page_tab_id>/detailed_stats
GET /v1/apps/<page_tab_id>/props
GET /v1/apps/<page_tab_id>
GET /v1/apps/<page_tab_id>/total_points
GET /v1/apps/<page_tab_id>/wager_entries
GET /v1/apps/<page_tab_id>/simple_points
GET /v1/apps/<page_tab_id>/simple_activities
POST /v1/apps/<page_tab_id>/registration/checkin
API Console
API Access allows you to query Stream and user data using RESTful API, as well as register for push notification from our CRM system. API Reference is broken into sections by topic: Meta Apps (Campaigns) Data, Stream Data, CRM Data.
Each Request must include api_key as parameter. You can generate an API key in the Manage Centre.You may try most of our API calls here. Your API Key will be automatically appended if available.
Segments Calls
GET /v1/segments
Description
Required Scope: segments
List available segments on the account. Will return three types of segments: tags, snapshots, and existing search filters
ResultArray of Objects
Resulting Structure| segment_type | tag/filter/snapshot |
| segment_id | If on the segment. ID is unique with in corresponding segment type |
| segment_name | Character descriptor for the segment |
GET /v1/segments/<segment_type>/<segment_id>/status
Description
Required Scope: segments
Obtain the status of a given segment including metrics on the size and fans
ResultDictionary with following metrics
Resulting Structure| fan_count | |
| email_count | |
| phone_count | |
| phone_subscribe_count | |
| email_subscribe_count | |
| last_update_timestamp | Update for the last update of the fan |
GET /v1/segments/<segment_type>/<segment_id>
Description
Required Scope: segments
Get list of fans tied to the segment. Object returned is minimalistic object as it's meant to be used for communication
Input Parameters| search_uid | Has to be supplied to get additional records. Currently result set may be limited and will return search_uid if paging is required |
| limit | Max size of the page. Values from 0 to 10000 are supported. If skipped, 1000 will be used |
Dictionary with meta and data elements. meta may include search_uid if output has to be paged.
Resulting Structure| fan_id | Primary key for the fan |
| phone | |
| first_name | |
| last_name | |
| is_subscribed | Boolean flag on whether there is explicit opt-in into email comm |
| is_phone_subscribed | Boolean flag on whether there is explicit opt-in into SMS comm |
Crm Calls
GET /v1/crm/activity_stats
Description
Required Scope: crm
Aggregate Call to obtain counters based on the custom values in fan activities
Input Parameters| campaign_title | Name of custom campaign |
| property_name | Name of the property to track |
Array of Counters
Resulting Structure| account_id | |
| campaign_title | |
| property_name | |
| counter |
GET /v1/crm/campaigns
Description
Required Scope: crm
Get a list of Campaigns on the account.
Input Parameters| q | Text based filter to specific campaigns |
Array of structures
Resulting Structure| account_id | |
| title | |
| page_tab_id | |
| stream_key | |
| app_type | |
| is_active | |
| creation_timestamp | |
| winner_fan_id |
GET /v1/crm/activities
Description
Required Scope: crm
Download incremental list of activities for the account.Paging is implemented with help of usage of max_activity_id and mix_activity_id parameters. In the first call, system will include in meta information about given IDs. Now, by supplying min_activity_id you can fetch next batch of records.
Input Parameters| min_activity_id | Window Specifier. Will return only activities with activity_id greater than given |
| max_activity_id | Window Specifier. Will return only activities with activity_id less than given |
| limit | Optional parameter to specify max row count. Max. allowed value is 200 |
| page_tab_id | Optional Filter to participants of specific campaign |
| activity_date | Optional Filter to participants for specific date |
| include_details | Boolean flag to include additional details: fan, idols, connections. Default = False |
Structure: {'meta': { 'order':'desc/asc','min_activity_id':xxx,'max_activity_id':xxx},'data':[] }. Data is array with following elements
Resulting Structure| activity_id | Unique Identifier for the activity |
| account_id | Tradable Bits Account ID |
| fan_id | Unique Identifier for the fan record |
| creation_date | ISO Date of activity |
| campaign_title | Title of the campaign |
| app_type | For contests - type of contest |
| page_tab_id | Contest ID reference (set for contests only) |
| opted_in_business_ids | Opted in business ids of the fan |
| is_subscribed | Opted in to Email Marketing |
| is_phone_subscribed | Opted in to SMS Marketing |
| creation_timestamp | ISO timestamp of activity |
| page_tab_id | Campaign ID reference |
| stream_key | If activity is tied to stream - reference for stream |
| ip_address | IP Address |
| user_key | Facebook/Spotify/etc User Key |
| name | Full Name |
| details | JSON structure of campaign details (varies by campaign) |
| fan | Fan Structure as per documentation |
| networks | List of connected networks |
| idol_names | List of connected Idols |
POST /v1/crm/activities
Description
Required Scope: crm
Submit new Activity as well as Fan details for data integration
Input Parameters| first_name | |
| last_name | |
| email * | |
| phone | |
| campaign_title | |
| province | |
| postal_code | |
| country_code | |
| is_subscribed | |
| is_phone_subscribed |
Structure matching the input with validated fields
GET /v1/crm/activities/<page_tab_id>/leaderboard
Description
Required Scope: crm
Fetch top 10 performing fans for a campaign
Input Parameters| show_hidden | Show fans who are hidden from the public leaderboard in the campaign. Default = False |
| limit | Limit the number of fans fetched from the leaderboard. Default = 10 |
An array of structures with following fields
Resulting Structure| rank | Leaderboard rank |
| fan_id | Unique Identifier for the fan record |
| display_name | |
| is_hidden | If the fan is hidden from the public leaderboard in the campaign (If applicable) |
| activity_timestamp | Timestamp of when the fan completed the activity (If applicable) |
| points | Number of points gained in the campaign (If applicable) |
| balance | Balance within the campaign (If applicable) |
| activity_duration_ms | Length of time spent for the campaign activity in ms (If applicable) |
| correct_count | Number of questions answered correctly (If applicable) |
GET /v1/crm/fan_tags
Description
Required Scope: crm
Fetch a list of existing crm fan tags for the purposes of synchronization. Request is limited to 10000 records max in a single result set.
Input Parameters| start_date | Window Specifier. Will return only tags with creation timestamp greater than given |
| end_date | Window Specifier. Will return only tags with creation timestamp less than given |
Array
Resulting Structure| tag_name | |
| tag_id | |
| fan_id | |
| creation_timestamp | |
| first_name | |
| last_name | |
GET /v1/crm/fans
Description
Required Scope: crm
Search for Fan records using CRM Search interface
Input Parameters| include_recent_entry | Include latest campaign into payload on result |
| include_tags | Include fan tags into payload on result |
| include_business_opt_ins | Include business opt ins into payload on result |
| name | Name or Email of the person in question |
| crm_active_days | |
| crm_inactive_days | |
| crm_start_active_date | |
| crm_end_active_date | |
| fan_youngest_age | |
| fan_oldest_age | |
| fan_incl_snapshot_uids | |
| fan_excl_snapshot_uids | |
| fan_tags | |
| fan_tag_relations | |
| fan_networks | |
| fan_is_subscribed | |
| fan_is_optout | |
| fan_is_phone_subscribed | |
| fan_postal_codes | |
| fan_provinces | |
| fan_rating | |
| fan_gender | |
| fan_source | |
| fan_metro_areas | |
| fan_start_creation_date | Format YYYY-MM-DD |
| fan_end_creation_date | Format YYYY-MM-DD |
| idol_names | |
| idol_relations | |
| ticket_event_name | |
| ticket_price_code | |
| ticket_start_purchase_date | |
| ticket_end_purchase_date | |
| ticket_venue_name | |
| ticket_venue_provinces | |
| ticket_purchased_days | |
| ticket_artist_name | |
| ticket_start_event_date | |
| ticket_end_event_date | |
| ticket_seat_price_min | |
| ticket_seat_price_max | |
| ticket_seat_count_min | |
| ticket_seat_count_max | |
| ticket_sales_count_min | |
| ticket_sales_count_max | |
| ticket_is_negative | |
| search_uid | If this parameter is supplied, we will continue returning records from previous search execution |
| limit | Maximum page size. Has to be less than a 1000 |
| max_count | Maximum total number of records retrieved. Max value of 1,000,000. Default = 100,000 |
Array with Meta structure as part of result
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags | |
| last_page_tab_id | |
| last_campaign_name | |
| opted_in_business_ids |
GET /v1/crm/fan_updates
Description
Required Scope: crm
Get the latest updated fans. The last_update_date parameter can be used to get fans which were updated after a particular date. The min_time_key can be used to fetch the next page of updated fans. Each page has a size limit of 1000.
Input Parameters| last_update_date | yyyy-mm-dd. Gets latest fans having last update date after this date. |
| min_time_key | The time key used to fetch the next page of updated fans. The format is '<unix_time>_<milliseconds>_<fan_id>'. Use the max_fan_time_key returned in the meta structure of previous request for fetching the next page. |
Structure: {'meta': { 'min_fan_time_key':'xxx', 'max_fan_time_key':xxx, 'count':xxx }, 'data':[] }. Data is array with following elements
Resulting Structure| fan_id | |
| account_id | |
| first_name | |
| last_name | |
| latitude | |
| longitude | |
| city | |
| province | |
| country_code | |
| metro_area | |
| postal_code | |
| ip_address | |
| is_optout | |
| is_subscribed | |
| is_phone_subscribed | |
| gender | |
| rating | |
| birth_date | |
| phone | |
| add_phone | |
| is_confirmed | |
| is_phone_confirmed | |
| display_name | |
| tags | |
| fields | |
| last_page_tab_id | |
| last_campaign_name | |
| fan_time_key | |
| creation_timestamp | |
| last_update_timestamp | |
| creation_timestamp_iso | ISO creation timestamp |
| last_update_timestamp_iso | ISO last update timestamp |
GET /v1/crm/fan_points
Description
Required Scope: crm
Get a list of currently awarded fan points
Input Parameters| start_date * | yyyy-mm-dd. |
| end_date * | yyyy-mm-dd. |
| point_uid | Optionally filter by point |
| fan_id | Optionally filter by fan |
| 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/crm/fan_points
Description
Required Scope: crm
Award fan points
Input Parameters| point_uid * | Point for the points to be associated with |
| fan_id * | Fan for the points to be associated with |
| point_count * | Number of points to award (can be negative) |
| point_type | One of 'points', 'atvenu', 'bestring'. Defaults to 'points' |
| reward_uid | Optionally associate the points with a reward |
| page_tab_id | Optionally associate the points with a campaign |
| activity_id | Optionally associate the points with an activity |
| session_uid | Optionally associate the points with a fan session |
| award_key | Optional deduplication key |
| fan_point_uid | |
| 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 |
GET /v1/crm/points
Description
Required Scope: crm
Get a fan leaderboard based on provided filters
Input Parameters| start_date | yyyy-mm-dd. One of start_date or end_date is required |
| end_date | yyyy-mm-dd. One of start_date or end_date is required |
| point_name * |
Array with Meta structure as part of result
Resulting Structure| point_name | |
| fan_id | |
| fan_point_count | number of points based of filter |
| rank | rank of fan among all fans based on filter |
| display_name |
POST /v1/crm/purchases
Description
Required Scope: crm
Upsert purchases via API.
Input Parameters| purchase_key * | A unique key for this purchase, recommended format {network}-{order_key}-{line_item_id} |
| network * | The network that the purchase originated from. |
| order_key * | An identifier for the order. Typically, an order will have multiple order items / purchases. |
| merchant_key * | An identifier for a specific merchant/seller which made the sale. |
| order_timestamp * | The timestamp when the purchase was made. |
| gross_sale_amount * | The gross sale amount made on this purchase. |
| net_sale_amount * | The net sale amount made on this purchase. |
| location_key | An identifier for specific location that the purchase was made. |
| customer_key | An identifier for the customer of this purchase. |
| The customer's email. | |
| phone | The customer's phone. |
| country | The customer's country, can be a country code or country name. |
| province | The customer's province i.e. British Columbia |
| city | The customer's city i.e. Vancouver |
| product_key | An identifier for the product attached to this purchase. |
| product_name | A human-readable name for the product. |
| product_category | The category that the product falls under. |
The newly created or updated purchase.
Resulting Structure| 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 the 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 purchase. |
| 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. | |
| phone | The customer phone associated with this purchase. |
| 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/purchases
Description
Required Scope: crm
Search for purchases for specific products, from a specific merchant and/or location, within a date range. Responses are paginated.
Input Parameters| network * | The network that the purchase originated from. |
| start_date * | All purchases made after this date will be returned. |
| end_date * | All purchases made before this date will be returned. |
| product_name | A product name, this field is a search field so all product names which contain this string will be returned. |
| merchant_key | Only return purchases which come from a specific merchant. |
| location_key | Only return purchases which are from a specific location. |
| next_purchase_key | Used for pagination, each response will contain a next_purchase_key field if there is more data to be fetched. |
Structure: {'meta': {'page_size': 500, 'next_purchase_key': 'somestring', 'count': 30}, 'data':[] }. Data is array with following elements
Resulting Structure| account_id | The tradablebits account ID |
| network | The network that this purchase originates from. |
| purchase_key | A unique key for this purchase. |
| order_key | An identifier for an order, a single order may have multiple order items / purchases. |
| location_key | An identifier for a specific location. |
| merchant_key | An identifier for a specific merchant/seller. |
| customer_key | An identifier for the customer associated with this order. |
| fan_id | The fan ID associated with this purchase. |
| order_timestamp | The timestamp of the purchase as a unix timestamp. |
| gross_sale_amount | The gross sale amount made on this purchase. |
| net_sale_amount | The net sale amount made on this purchase. |
| deduction_amount | The amount deducted on this purchase such as discounts or refunds. |
| product_key | An identifier for the product attached to this purchase. |
| product_name | A human-readable name for the product. |
| product_category | The category that this product falls under. |
| The customer email associated with this purchase_key. | |
| phone | The customer phone associated with this purchase_key. |
| country_code | The customer's country code. |
| province | The customer's province. |
| city | The customer's city. |
| order_timestamp_iso | The order timestamp in ISO format. |
GET /v1/crm/tickets
Description
Required Scope: crm
Download incremental list of tickets for the account. Paging is implemented with help of usage of max_ticket_id and min_ticket_id parameters. In the first call, system will include in meta information about given IDs. Now, by supplying min_ticket_id you can fetch next batch of records.
Input Parameters| min_ticket_id | Window Specifier. Will return only tickets with ticket_id greater than given |
| max_ticket_id | Window Specifier. Will return only tickets with ticket_id less than given |
| min_purchase_date | Date filter option. Will return only tickets on or after a given date |
| max_purchase_date | Date filter option. Will return only tickets on or prior to a given date |
| min_last_update_date | Date filter option. Will return only tickets on or after a given date |
| max_last_update_date | Date filter option. Will return only tickets on or prior to a given data |
| Allows you to filter tickets to specific user/email address | |
| limit | Max row count. Max. allowed value is 1000 |
| data | Additional fields to include: supported value: fan |
| include_deleted | If set to true, return will include deleted tickets. Default = False |
Structure: {'meta': { 'order':'desc/asc','min_ticket_id':xxx,'max_ticket_id':xxx},'data':[] }. Data is array with following elements
Resulting Structure| ticket_id | Unique Identifier for the ticket |
| ticket_key | Remote Tickey Key |
| account_id | Tradable Bits Acount ID |
| email on the ticket | |
| network | type of remote network to fetch ticket |
| event_key | Event Key in remote system |
| event_date | ISO date of the event |
| event_name | Event Name |
| purchase_timestamp | ISO Date |
| paid_amount | Total Paid Amount |
| num_seats | Number of tickets/seats on the purchase |
| artist_name | Artist Name |
| price_code | Price Code or Level |
| venue_name | Name of Venue |
| city | City |
| province | Province or State |
| country_code | ISO country code |
| metro_area | DMA or CMA Area (Currently only for US/CA) |
| postal_code | Postal Code / ZIP |
| customer_key | ID of customer in remote system |
| is_deleted | True if ticket deleted |
| last_updated_timestamp | ISO date of last update |
GET /v1/crm/tickets/<ticket_id>
Description
Required Scope: crm
Get single ticket by ticket id
ResultSingle record. Data is array with following elements
Resulting Structure| ticket_id | Unique Identifier for the ticket |
| ticket_key | Remote Tickey Key |
| account_id | Tradable Bits Acount ID |
| email on the ticket | |
| network | type of remote network to fetch ticket |
| event_key | Event Key in remote system |
| event_date | ISO date of the event |
| event_name | Event Name |
| purchase_timestamp | ISO Date |
| paid_amount | Total Paid Amount |
| num_seats | Number of tickets/seats on the purchase |
| artist_name | Artist Name |
| price_code | Price Code or Level |
| venue_name | Name of Venue |
| city | City |
| province | Province or State |
| country_code | ISO country code |
| metro_area | DMA or CMA Area (Currently only for US/CA) |
| postal_code | Postal Code / ZIP |
| customer_key | ID of customer in remote system |
| is_deleted | True if ticket deleted |
| last_updated_timestamp | ISO date of last update |
POST /v1/crm/tickets
Description
Required Scope: crm
Create new ticket and Corresponding Fan Record
Input Parameters| first_name * | |
| last_name * | |
| email * | |
| purchase_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| paid_amount * | Numeric value for line item |
| num_seats * | Number of seats purchased |
| event_date * | ISO8601 Encoded String |
| event_name * | |
| phone | |
| customer_key | Key of the customer in the remote system |
| ticket_key | Optional. Unique identifier for the line item (i.e. unique per price code and amount). |
| price_code | Optional. Price level or code of line item |
| is_subscribed | Subscribed to email |
| is_phone_subscribed | Subscribed to phone |
| city | |
| province | |
| postal_code | |
| country_code | |
| artist_name | |
| venue_name | |
| event_key | |
| network | |
| order_key | |
| is_deleted | Boolean Value |
| fan_source | Text identifier if fan is to be created |
Created Record. Data will be returned as it was loaded in the system. I.e. sanitized
Resulting Structure| event_date | |
| event_key | |
| artist_name | |
| venue_name | |
| event_name | |
| ticket_id | |
| ticket_key | |
| price_code | |
| purchase_timestamp | |
| paid_amount | |
| num_seats | |
| network | |
| fan_id | |
| first_name | |
| last_name | |
| phone | |
| is_subscribed | |
| is_phone_subscribed | |
| province | |
| country_code | |
| city | |
| metro_area | |
| postal_code | |
| order_key | |
| is_deleted | |
| last_update_timestamp | |
| status | success or duplicate if ticket already exists |
POST /v1/crm/bulk_tickets
Description
Required Scope: crm
Create up to 100 new tickets and Corresponding Fan Records. Takes in a list of tickets with the same structure and requirements as POST /v1/crm/tickets
Input Parameters| first_name * | |
| last_name * | |
| email * | |
| paid_amount * | Numeric value for line item |
| num_seats * | Number of seats purchased |
| purchase_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| event_date * | ISO8601 Encoded String |
| event_name * | |
| event_key * | |
| phone | |
| customer_key | Key of the customer in the remote system |
| ticket_key | Unique identifier for the line item (i.e. unique per price code and amount). |
| price_code | Price level or code of line item |
| is_subscribed | Subscribed to email |
| is_phone_subscribed | Subscribed to phone |
| city | |
| province | |
| postal_code | |
| country_code | |
| artist_name | |
| venue_name | |
| network | |
| order_key | |
| is_deleted | Boolean Value |
A list of Created Records. Data will be returned as it was loaded in the system. I.e. sanitized
Resulting Structure| ticket_id | |
| account_id | |
| ticket_key | |
| customer_dsn | |
| network | |
| purchase_timestamp | |
| paid_amount | |
| order_amount | |
| num_seats | |
| fan_id | |
| event_date | |
| event_name | |
| event_key | |
| artist_name | |
| venue_name | |
| price_code | |
| city | |
| province | |
| country_code | |
| customer_key | |
| postal_code | |
| metro_area | |
| venue_province | |
| order_key | |
| ticket_category | |
| import_uid | |
| is_deleted | |
| ticket_type | |
| ticket_type_category | |
| creation_timestamp | |
| last_update_timestamp | |
| status |
GET /v1/crm/tickets/events
Description
Required Scope: crm
Get all event tickets or search by event_name, event_key, event_date or venue_name
Input Parameters| event_name | Must be exact name |
| event_key | |
| event_date | Format YYYY-MM-DD |
| network | |
| venue_name | Must be exact name |
| is_ticketless_only | Boolean, not allowed to be passed in combination with event_key, event_date, event_name or venue_name |
Structure: {'meta': { 'count': ### }, 'data': []}. Data is an array with the following elements
Resulting Structure| event_uid | Unique identifier for the event |
| account_id | |
| event_key | |
| event_name | |
| venue_name | |
| artist_name | |
| event_date | |
| creation_timestamp | |
| network | |
| notes | |
| label_name | |
| event_type |
POST /v1/crm/tickets/events
Description
Required Scope: crm
Create, update or delete a ticket event.
Input Parameters| action | create / update / delete. Defaults to create |
| event_uid | Unique identifier for the event. Required for delete. Event_uid or event_key required for update |
| event_name * | Must be exact name |
| event_key * | |
| event_date * | Format YYYY-MM-DD |
| network * | |
| venue_name | |
| artist_name | |
| notes | |
| label_name | |
| event_type |
Created Record. Data will be returned as it was loaded in the system. I.e. sanitized
Resulting Structure| event_uid | |
| account_id | |
| event_key | |
| event_name | |
| venue_name | |
| artist_name | |
| event_date | |
| creation_timestamp | |
| network | |
| notes | |
| label_name | |
| event_type | |
| status |
GET /v1/crm/ticket_stats
Description
Required Scope: crm
Get stats for tickets over a specified time range.
Input Parameters| max_purchase_date | Format YYYY-MM-DD. |
| min_purchase_date | Format YYYY-MM-DD. |
| event_name | Must be exact name. |
| event_key | |
| event_date | Format YYYY-MM-DD. |
| venue_name | Must be exact name |
| artist_name | |
| event_specific | Format 'true' or 'false'. Determines whether new/returning stats are by date only or by event as well. Default = False |
Single record. Data is an object with the following elements
Resulting Structure| returning_fans_count | |
| new_fans_count | |
| sales_count | |
| seats_count | |
| revenue |
GET /v1/crm/registrations
Description
Required Scope: crm
Query Wristband/RFID registrations from the database
Input Parameters| start_date | Date filter option. Will return only tickets on or after a given date |
| end_date | Date filter option. Will return only tickets on or prior a given date |
| Allows you to filter tickets to specific user/email address | |
| limit | Max row count. Default = 1000 |
Structure: {'meta': { 'count':xxx },'data':[] }. Data is array with following elements
Resulting Structure| registration_key | Unique Identifier for the registration |
| order_key | Remote Ticket Key |
| account_id | Tradable Bits Account ID |
| email on the ticket | |
| event_date | ISO date of the event |
| registration_timestamp | Timestamp of registration. Unix Time |
| creation_timestamp | Timestamp of import. Unix Time |
| price_code | Price Code or Level |
POST /v1/crm/registrations
Description
Required Scope: crm
Create new registration and Corresponding Fan Record
Input Parameters| first_name * | |
| last_name * | |
| phone | |
| email * | |
| registration_key * | Unique identifier for the line item |
| registration_timestamp * | YYYY-MM-DD HH:MI:SS in GMT timezone |
| order_key | |
| price_code | Price level or code of line item |
| event_date | Date of the Event. ISO Date |
Created Record. Data will be returned as it was loaded in the system. I.e. sanitized
Resulting Structure| registration_key | Unique Identifier for the registration |
| order_key | Remote Ticket Key |
| account_id | Tradable Bits Account ID |
| email on the ticket | |
| event_date | ISO date of the event |
| registration_timestamp | Timestamp of registration. Unix Time |
| creation_timestamp | Timestamp of import. Unix Time |
| price_code | Price Code or Level |
GET /v1/crm/registrations/scans
Description
Required Scope: crm
Get registration and scan data by scan_group_name. Results are ordered by scan_key ascending.
Input Parameters| scan_group_name * | scan_group_name / group_set_name identifier for different groups of scans. |
| start_date * | Scan creation start_date, scans between start_date and end_date will be fetched. |
| end_date * | Scan creation end_date, scans between start_date and end_date will be fetched |
| network * | The ticketing network. |
| next_scan_key | Used for pagination, each response will contain a 'next_scan_key' value which is to be supplied in the subsequent request in order to page through all records in the response. It does not need to be supplied on the first request to this endpoint. |
| venue_name | Venue name for the event. |
| event_date | Date of the event. |
Scan and registration data.
Resulting Structure| scan_key | An identifier associated with this scan |
| account_id | TradableBits account ID |
| network | Network associated with this scan |
| fan_id | Fan ID associated with this scan |
| event_key | The event key linked to this scan |
| is_success | Boolean field, represents whether the scan was successful |
| access_mode | The type of scan i.e. IN, OUT |
| scan_group_name | The group_set_name / scan_group_name for this scan. |
| site_name | Site name associated with this scan. |
| site_id | The integer ID for the site. |
| node_name | |
| zone_name | |
| scan_timestamp | The time that scan occurred |
| registration_key | The registration key. |
| ticket_order_key | The order key of the associated ticket. |
| event_name | The name of the event linked to the registration |
| event_date | The date of the event linked to the registration. |
| venue_name | Venue name linked to the registration |
| first_name | |
| last_name | |
| phone | |
| country_code | |
| province | |
| postal_code | |
| registration_timestamp | Timestamp when registration occurred |
| barcode | Wristband barcode associated with this scan/registration. |
POST /v1/crm/fans
Description
Required Scope: crm
Create new Fan Record
Input Parameters| first_name | |
| last_name | |
| 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 | |
| birth_date | |
| ip_address | |
| latitude | |
| longitude | |
| business_<business_id> | Send business_<business_id> as the field and true/false/on/off as the value. True indicates a fan is opted in to the business, false will opt a fan out of the business. |
| fan_source | Text identifier if fan is to be created |
| is_optout |
Created Record
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
GET /v1/crm/fans/<fan_id>/identifiers
Description
Required Scope: crm
Get fan identifiers for a specific Fan ID
ResultA list of fan identifiers
Resulting Structure| account_id | |
| fan_id | |
| network | |
| identifier_value | |
| creation_timestamp | |
| creation_timestamp_iso |
GET /v1/crm/fans/<fan_id>
Description
Required Scope: crm
Get Specific fan record via ID
ResultFollowing structure
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
POST /v1/crm/fans/<fan_id>
Description
Required Scope: crm
Update Fan Record
Input Parameters| first_name | |
| last_name | |
| password | |
| display_name | |
| gender | Must be male, female, diverse, other, or empty. |
| is_subscribed | true/false/on/off |
| is_phone_subscribed | |
| phone | |
| birth_date | |
| ip_address | |
| country_code | |
| province | If used, country_code is required |
| city | If used, country_code is required |
| postal_code | If used, country_code is required |
| business_<business_id> | Send business_<business_id> as the field and true/false/on/off as the value. True indicates a fan is opted in to the business, false will opt a fan out of the business. |
Updated Record
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| gender | |
| tags |
DELETE /v1/crm/fans/<fan_id>
Description
Required Scope: crm
Delete Record
ResultBoolean
GET /v1/crm/fans/<fan_id>/points
Description
Required Scope: crm
Get Fan points
ResultFollowing structure
Resulting Structure| fan_id | |
| point_uid | |
| point_name | |
| point_count |
POST /v1/crm/fans/<fan_id>/points
Description
Required Scope: crm
award a fan points
Input Parameters| point_name * | |
| point_count * |
[]
GET /v1/crm/fans/<fan_id>/idols
Description
Required Scope: crm
Fetch list of idols for a given Fan
Input Parameters| label_name | Limit Idols to a specific label |
Array of Idols
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| idol_type |
POST /v1/crm/fans/<fan_id>/idols
Description
Required Scope: crm
Add or remove idol association
Input Parameters| action * | add/delete |
| idol_uid | One of idol_uid or idol_name is required. |
| idol_name | Name for a given (as alternative to UUID). One of idol_uid or idol_name is required. |
Array of current Fan Idols
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| idol_type |
GET /v1/crm/fans/<fan_id>/registrations
Description
Required Scope: crm
Obtain a list of known registrations for the fan. Registration is tied to RFID bracelet or some form of ticket
Input Parameters| limit | Record Limit |
Array of records
Resulting Structure| registration_key | |
| account_id | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| fan_id | |
| registration_timestamp | |
| creation_timestamp | |
| first_name | |
| last_name | |
| phone | |
| ticket_id | |
| address | |
| city | |
| province | |
| country_code | |
| postal_code | |
| birth_date | |
| is_minor |
POST /v1/crm/fans/<fan_id>/registrations
Description
Required Scope: crm
Create new Registration Record for a given Fan
Input Parameters| registration_timestamp | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| registration_timestamp | |
| first_name | |
| last_name | |
| phone | |
| ticket_id | |
| address | |
| city | |
| province | |
| country_code | |
| postal_code | |
| birth_date | |
| is_minor |
Array of latest registrations
Resulting Structure| registration_key | |
| account_id | |
| ticket_order_key | |
| price_code | |
| event_date | |
| barcode | |
| fan_id | |
| registration_timestamp | |
| creation_timestamp | |
| first_name | |
| last_name | |
| phone | |
| ticket_id | |
| address | |
| city | |
| province | |
| country_code | |
| postal_code | |
| birth_date | |
| is_minor |
GET /v1/crm/fans/<fan_id>/activities
Description
Required Scope: crm
Obtain a list of activities for a given Fan
Input Parameters| limit | Record Limit |
| campaign_title | Limit results to specific campaign |
Array of records
Resulting Structure| account_id | |
| fan_id | |
| creation_date | |
| campaign_title | |
| props |
POST /v1/crm/fans/<fan_id>/activities
Description
Required Scope: crm
Create new Activity Record for a given Fan
Input Parameters| campaign_title * | Name of custom campaign |
| field_* | Additional meta data as per defined custom fields |
Array of latest activities
Resulting Structure| account_id | |
| fan_id | |
| creation_date | |
| campaign_title | |
| props |
GET /v1/crm/fields
Description
Required Scope: crm
Get array of defined custom fields on the account
Result Resulting Structure| crm_field_key | |
| account_id | |
| field_type | |
| creation_timestamp | |
| field_options | |
| is_active | |
| is_global |
GET /v1/crm/search_filters
Description
Required Scope: crm
Get array of search filters
Input Parameters| group name | Filter group name |
| creation_start_date | String in the form 'YYYY-MM-DD' |
| creation_end_date | String in the form 'YYYY-MM-DD' |
Array of search filters
Resulting Structure| filter_uid | |
| filter_name | |
| account_id | |
| creation_timestamp | |
| last_search_count |
GET /v1/crm/fan_stats
Description
Required Scope: crm
Get stats pertaining to fans captured by the filter provided
Input Parameters| filter_name * |
Fan stats object based on filter supplied
Resulting Structure| fans | Object containing general information such as total number of fans |
| fan_demographics | Object containing gender and fan rating breakdowns |
| top_countries | Object showing fan locations by country |
| top_metro_areas | Object showing fan locations by metro area |
| top_locations | Object showing fan locations by region with further breakdowns |
| fan_metrics | Age, gender, and rating counts |
| postal_demographics | Census breakdown percentages by ethnicity, education, income, family makeup |
GET /v1/crm/monitored_ip_addresses
Description
Required Scope: crm
Get list of monitored ip addresses on the account
Result Resulting Structure| page_tab_id | |
| ip_address | |
| is_blocked | True if the address is banned, false if it is allowed |
| creation_timestamp |
POST /v1/crm/monitored_ip_addresses
Description
Required Scope: crm
Block or allow an IP address or CIDR
Input Parameters| ip_address * | IP Address or CIDR |
| is_blocked * | True to ban users at this ip address, false to allow them |
| page_tab_id | If included, will ban or allow the given address for only this page tab |
The created record
Resulting Structure| page_tab_id | |
| ip_address | |
| is_blocked | True if the address is banned, false if it is allowed |
| creation_timestamp |
DELETE /v1/crm/monitored_ip_addresses
Description
Required Scope: crm
Delete a blocked or allowed IP Address
Input Parameters| ip_address * | IP Address or CIDR |
| is_blocked * | |
| page_tab_id |
The deleted record
Resulting Structure| page_tab_id | |
| ip_address | |
| is_blocked | True if the address is banned, false if it is allowed |
| creation_timestamp |
Streams Calls
GET /v1/streams
Description
Required Scope: streams
Produce a list of currently available streams.
Result Resulting Structure| stream_key | |
| account_id | |
| creation_timestamp | |
| stream_name | |
| props | |
| virtual_domain | |
| css_text | |
| javascript_text | |
| record_limit | |
| trust_level | |
| media_map | |
| is_public |
GET /v1/streams/<stream_key>/records
Description
Required Scope: streams
Search for approved records in the stream
Input Parameters| networks | |
| label_key | |
| sku | |
| is_graphic | yes, no or empty |
| min_time_key | Max and Min time keys is a way to page through results. As part of Result - system returns max_time_key/min_time_key in the data. |
| max_time_key | Max and Min time keys is a way to page through results. As part of Result - system returns max_time_key/min_time_key in the data. |
| q | |
| start_latitude | |
| end_latitude | |
| start_longitude | |
| end_longitude |
{meta:{min_time_key:xx, max_time_keey:xx, row_count:xxx },data:[] }
Resulting Structure| stream_key | |
| feed_record_id | |
| record_key | |
| props | |
| creation_timestamp | |
| image_url | |
| src_image_url | |
| video_url | |
| caption | |
| network | |
| record_url | |
| latitude | |
| longitude | |
| links | |
| link_url | |
| link_name | |
| author_id | |
| author_user_key | |
| author_screen_name | |
| author_name | |
| author_image_url | |
| author_status |
POST /v1/streams/<stream_key>/records
Description
Required Scope: streams
Create new Stream Record
Input Parameters| name | |
| image_url | |
| caption | |
| latitude | |
| longitude | |
| props_* | Ability to store any meta data as part of the record |
Newly Created Record
Resulting Structure| stream_key | |
| feed_record_id | |
| record_key | |
| props | |
| creation_timestamp | |
| image_url | |
| src_image_url | |
| video_url | |
| caption | |
| network | |
| record_url | |
| latitude | |
| longitude | |
| links | |
| link_url | |
| link_name | |
| author_id | |
| author_user_key | |
| author_screen_name | |
| author_name | |
| author_image_url | |
| author_status |
GET /v1/streams/<stream_key>
Description
Required Scope: streams
Get Summary Stats on the stream
Input Parameters| data | Comma separated list of sections: words, hashtags, labels |
| label_key | Label Filter |
| start_time | Date filter (specified as unix time) |
| end_time | Date filter (specified as unix time) |
Summary Structure Record
Resulting Structure| stream_key | |
| stream_name | |
| total_stored | |
| total | |
| approved_total | |
| authors | |
| reach | |
| last_record_timestamp | |
| words | |
| hashtags | |
| labels |
GET /v1/streams/<stream_key>/<feed_record_id>
Description
Required Scope: streams
Get individual record
ResultRecord Data
Resulting Structure| stream_key | |
| feed_record_id | |
| record_key | |
| props | |
| creation_timestamp | |
| image_url | |
| src_image_url | |
| video_url | |
| caption | |
| network | |
| record_url | |
| links | |
| link_url | |
| link_name | |
| author_id | |
| author_user_key | |
| author_screen_name | |
| author_name | |
| author_image_url | |
| author_status |
POST /v1/streams/<stream_key>/<feed_record_id>
Description
Required Scope: streams
Approve individual Record or Label it accordingly
Input Parameters| action * | approve/remove/label/unlabel |
| label_key |
Update Record Data
Resulting Structure| stream_key | |
| feed_record_id | |
| record_key | |
| props | |
| creation_timestamp | |
| image_url | |
| src_image_url | |
| video_url | |
| caption | |
| network | |
| record_url | |
| links | |
| link_url | |
| link_name | |
| author_id | |
| author_user_key | |
| author_screen_name | |
| author_name | |
| author_image_url | |
| author_status |
Sessions Calls
POST /v1/sessions/wifi_fans
Description
Required Scope: sessions
This endpoint enables third party apps to pass Wifi Authentication Information
Input Parameters| network * | Connected network. Network value can drive other require arguments. Supported: facebook, spotify, email |
| access_token | Mandatory for Facebook/Spotify |
| Optional for Facebook/Spotify | |
| first_name | Optional for Facebook/Spotify |
| last_name | Optional for Facebook/Spotify |
| activity_name | Reference to the Activity or Event name. |
| device_id | Hardware reference if mobile app is used |
| device_network | one of ios/android |
true if call is successful, error otherwise
POST /v1/sessions/check
Description
Required Scope: sessions
Quick endpoint to confirm the entity of the registered user for the purpose of handling signup
Input Parameters| phone | One of phone or email are required |
| One of phone or email are required |
Structure as below
Resulting Structure| fan_id | Fan ID of the records |
| first_name | First Name |
| last_name | Last Name |
POST /v1/sessions/signup
Description
Required Scope: sessions
This endpoint enables third-party apps to push email signup or some other form of activity into our CRM.
Input Parameters| One of phone or email are required | |
| phone | One of phone or email are required |
| first_name | |
| last_name | |
| birth_date | String in the form 'YYYY-MM-DD' |
| city | City. country_code is required if included. |
| country_code | 2 letter country code or full country name |
| postal_code | Postal Code in a given country. country_code is required if included |
| province | Province name. country_code is required if included |
| ip_address | Will take REMOTE_ADDR if omitted |
| device_id | Hardware reference if mobile app is used |
| device_network | one of ios/android |
| field_xxxx | Custom field value for configured custom fields |
| is_unique_activity | true/false - enforce unique participation in the campaign |
| campaign_name | Campaign Connection, if call is meant to be associated with campaign |
| page_tab_id | Campaign Connection, if call is meant to be associated with campaign. This field should be used instead of the campaign_name field if possible and will supersede it if filled |
| tag_name | CRM Tag to apply to the user. Can be specified multiple times in the payload |
| tag_names | As alternative to tag_name, tags can be supplied as comma separated list |
| business_id | Opt-in to a specific business, if applicable |
| idol_name | Idol to associate with the user |
Structure as below
Resulting Structure| fan_id | Fan ID of the records |
| activity_id | Activity ID if it was created properly |
POST /v1/sessions/connect
Description
Required Scope: sessions
This call allows to initialize new session and potentially create new fan Record in the system. It can be used for native and website integration and is essential for proper integration.
Input Parameters| network | Connected network. Network value can drive other require arguments. An empty string as network value is used to create a guest session without a fan record. Most common values: facebook, spotify, yinzcam, twitter, register, email, verify_sms, verify_email, submit_verification_code |
| business_id * | |
| page_tab_id | |
| access_token | |
| ip_address | |
| name | |
| phone | |
| password | |
| access_secret | |
| is_accepted | Flag to confirm terms acceptance. Required if terms_required is returned |
| device_id | |
| device_network |
New Session Object (or structure to represent a step in login flow
Resulting Structure| session_uid | |
| fan_id | |
| account_id | |
| props | |
| expiration_timestamp |
GET /v1/sessions/<session_uid>
Description
Required Scope: sessions
Get existing Session using ID
ResultRecord
Resulting Structure| session_uid | |
| fan_id | |
| account_id | |
| props | |
| expiration_timestamp |
GET /v1/sessions/<session_uid>/fan
Description
Required Scope: sessions
Fetch current Fan Record
ResultFollowing Structure
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| image_url | |
| gender | |
| tags |
POST /v1/sessions/<session_uid>/fan
Description
Required Scope: sessions
Update Current Fan Record
Input Parameters| first_name | |
| last_name | |
| password | |
| is_subscribed | true/false/on/off |
| is_phone_subscribed | true/false/on/off |
| phone | |
| birth_date | |
| ip_address | |
| props_* | update props |
| field_* | update fields |
| tag_* | update tags |
Updated Record
Resulting Structure| fan_id | |
| account_id | |
| name | |
| first_name | |
| last_name | |
| province | |
| latitude | |
| longitude | |
| creation_timestamp | |
| ip_address | |
| country_code | |
| city | |
| is_subscribed | |
| is_phone_subscribed | |
| rating | |
| phone | |
| birth_date | |
| metro_area | |
| postal_code | |
| fields | |
| image_url | |
| gender | |
| tags |
GET /v1/sessions/<session_uid>/points
Description
Required Scope: sessions
Get Fan points
ResultFollowing structure
Resulting Structure| fan_id | |
| point_uid | |
| point_name | |
| point_count |
Idols Calls
POST /v1/idols
Description
Required Scope: idols
Create new idol in the database
Input Parameters| idol_name * | Name of the new idol |
| spotify_uid | Optional Spotify UID if it's available |
| artist_id | Optional Artist ID |
| discovery_id | Optional Discovery ID |
| idol_type | Optional idol type. Valid options are 'artist', 'sponsor', 'podcast', 'team', or 'other'. If left empty, system will attempt to match a spotify artist to the name, and if it cannot be found will set type as 'other' |
idol structure
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| link_url | |
| idol_type |
GET /v1/idols
Description
Required Scope: idols
Search for an idols in the database
Input Parameters| idol_name | Search Expression for an idol |
| label_name | Limit Idols to a specific label |
Array of idol structures
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| link_url | |
| idol_type |
GET /v1/idols/<idol_uid>
Description
Required Scope: idols
Obtain an idol for a given idol_uid
ResultA structure for a given idol as follows
Resulting Structure| spotify_follower_count | |
| spotify_uid | |
| description | |
| account_id | |
| idol_uid | |
| idol_name | |
| media_uid | |
| image_url | |
| link_url | |
| idol_type |
GET /v1/idols/events
Description
Required Scope: idols
Based on the search parameters return a list of Idol Events.
Input Parameters| idol_uid | |
| venue_name | |
| q | |
| label_name | |
| start_date | |
| end_date |
Array of JSON records matching the search
Resulting Structure| event_uid | |
| account_id | |
| idol_uid | |
| start_timestamp | |
| end_timestamp | |
| venue_name | |
| city | |
| province | |
| country_code | |
| event_url | |
| ticket_url | |
| label_name | |
| idol_name | |
| facebook_id | |
| media_uid | |
| image_url |
Reports Calls
GET /v1/reports
Description
Required Scope: reports
Get all shared reports associated with the current account.
ResultArray of JSON objects as per structure below
Resulting Structure| report_uid | Identifier of the report |
| report_name | Name of the report |
| report_type | Type of the report. One of 'adwords_adaccount', 'app', 'artist_charts', 'business', 'crm', 'fb_adaccount', 'idol', 'idol_details', 'sms', 'stream', 'ticket_compare', 'ticket_geo', 'ticket_sales', 'tracker' |
| start_date | Start date for the report's data |
| end_date | End date for the report's data |
| last_access_timestamp | Timestamp for when the report was last accessed |
GET /v1/reports/<report_uid>
Description
Required Scope: reports
Get data for a shared report.
ResultStructure: {'<report_type>': {}}. Corresponding object to the report's type is the data for the report, whose structure depends on the report's type. Below is structure for 'fb_adaccount' stats report.
Resulting Structure| spend | Total spending |
| conversion | Total sales value attributable to ads |
| offline_conversion | Sales value attributable to offline conversion |
| conversion_count | Number of sales |
| impressions | Total number of impressions |
| reach | Total number of unique people reached |
| frequency | Average frequency per unique person |
| cpm | Cost-per-thousand |
| cpa | Cost-per-action |
| roi | Return on investment rate |
| clicks | Total number of clicks |
| ctr | Clickthrough rate |
| cpc | Cost-per-click |
Ads Calls
POST /v1/ads/projects/<project_uid>/budget_lines
Description
Required Scope: ads
Create a new budget line for an ad project
Input Parameters| name * | Name of the budget line |
| budget_amount * | Monetary amount of budget line |
| notes * | Budget line notes |
JSON object as per structure below
Resulting Structure| project_line_uid | |
| project_uid | |
| creation_timestamp | |
| budget_amount | |
| ip_address | |
| name | |
| notes | |
| campaign_names | |
| currency | |
| creation_timestamp_iso |
Misc Calls
GET /v1/trackers
Description
Required Scope: misc
Get a list of recently created Trackers (last 500 trackers). The date range will default to searching between now and 31 days in the past if neither option is specified
Input Parameters| min_creation_date | Minimum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
| max_creation_date | Maximum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
Array of JSON objects as per structure below
Resulting Structure| tracker_id | Unique identifier for tracker |
| account_id | Account id associated with the tracker |
| creation_timestamp | UNIX timestamp for creation |
| tracker_name | Name for the tracker |
| tracker_group_name | |
| target_url | |
| virtual_domain | |
| tracker_key | |
| purchase_event_wildcard | Purchase event name wildcard, used to match purchase events to trackers. |
| tracker_url | |
| tracker_marketing_group_name | |
| network | |
| attributed_purchase_count | |
| attributed_purchase_amount | |
| total_tracker_click_count | |
| creation_timestamp_iso | Formatted yyyy-mm-dd : hh:mm:ss timestamp |
GET /v1/trackers/<tracker_id>
Description
Required Scope: misc
Get individual tracker as specified by ID. The date range will default to searching between now and 31 days in the past if neither option is specified
Input Parameters| min_creation_date | Minimum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
| max_creation_date | Maximum date to use when searching for aggregated stats for the tracker. Must be of the format "%m/%d/%y" |
The following JSON structure will be returned if a tracker with the inputted ID exists for your account. Otherwise an error will be returned
Resulting Structure| tracker_id | Unique identifier for tracker |
| account_id | Account id associated with the tracker |
| creation_timestamp | UNIX timestamp for creation |
| tracker_name | Name for the tracker |
| tracker_group_name | |
| target_url | |
| virtual_domain | |
| tracker_key | |
| purchase_event_wildcard | Purchase event name wildcard, used to match purchase events to trackers. |
| tracker_url | |
| tracker_marketing_group_name | |
| network | |
| attributed_purchase_count | |
| attributed_purchase_amount | |
| total_tracker_click_count | |
| creation_timestamp_iso | Formatted yyyy-mm-dd : hh:mm:ss timestamp |
POST /v1/trackers
Description
Required Scope: misc
Create New Tracker for measurement of redirect performance. This call allows for the creation of Tradable Bits Trackers
Input Parameters| virtual_domain * | Domain. Must be preconfigured and setup by Tradable Bits |
| target_url * | |
| tracker_name * | Name for the tracker, maximum 128 characters |
| tracker_group_name * | |
| network | spotify, instagram, facebook, google, X or custom. Will default to custom if not specified or not in the list of valid networks |
| tracker_key | Must be alphanumeric. One will be generated if not supplied |
| purchase_event_wildcard | Purchase event name wildcard, used to match purchase events from sales pixel to trackers. |
| tracker_marketing_group_name | Max length 64 characters |
| page_tab_id |
Upon Success, call will return a structure for created tracker
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 | |
| tracker_url | |
| tracker_marketing_group_name | |
| attributed_purchase_count | |
| attributed_purchase_amount | |
| total_tracker_click_count | |
| creation_timestamp_iso | Formatted yyyy-mm-dd : hh:mm:ss timestamp |
GET /v1/trackers/sales_pixel
Description
Required Scope: misc
Get sales pixel 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 list of objects with the following structure
Resulting Structure| tracker_event_uid | |
| creation_timestamp | |
| purchase_amount | |
| is_clicked | |
| tracker_id | |
| fan_id | |
| activity_id | |
| ip_address | |
| device_type | |
| province | |
| country_code | |
| purchase_event_name | |
| host_name | |
| ticket_id | |
| order_key | |
| purchase_key | |
| quantity | |
| purchase_event_details | |
| currency | |
| url_param_props |
GET /v1/props/<prop_name>
Description
Required Scope: misc
This call allows to store and retrieve back json data structure. Primary use for this call is some form of simple voting, which doesn't require any cheater or inappropriate use detection
Input Parameters| props | Data structure to save |
The value currently stored under this prop_name
GET /v1/geoip
Description
Required Scope: misc
Get regional information from an IP address
Input Parameters| ip_address | IPv4 or IPv6 address. otherwise caller ip will be used |
Regional information associated with that IP address
Resulting Structure| city | |
| region_name | |
| latitude | |
| longitude | |
| country_name | |
| postal_code |
GET /v1/shp_lookup
Description
Required Scope: misc
Lookup product on Shopify
Input Parameters| query |
A list of matching shopify products
POST /v1/yinzcam_subscription
Description
Required Scope: misc
Part of the integration with Yinzcam for push tokens sync
Input Parameters| user_key * | |
| push_token * | |
| device_network * |
Boolean Value of True
GET /v1/account_ad_stats
Description
Required Scope: misc
Fetch ad stats for the account
Input Parameters| start_date * | |
| end_date * | |
| network |
A list of structures with the following fields
Resulting Structure| network | Ad platform, e.g. facebook, twitter |
| spend | |
| impressions | |
| clicks | |
| conversion_amount | |
| conversion_count | |
| offline_conversion_amount | |
| offline_conversion_count | |
| custom_conversion_count | |
| custom_conversion_amount | |
| custom_offline_conversion_count | |
| custom_offline_conversion_amount | |
| roas | |
| cpc | |
| cpm |
GET /v1/account_ad_stats_by_campaign
Description
Required Scope: misc
Fetch ad stats for the account, grouped by campaign
Input Parameters| start_date * | |
| end_date * | |
| network |
A list of structures with the following fields
Resulting Structure| network | Ad platform, e.g. facebook, twitter |
| ad_account_key | |
| campaign_key | |
| campaign_name | |
| spend | |
| impressions | |
| clicks | |
| conversion_amount | |
| conversion_count | |
| offline_conversion_amount | |
| offline_conversion_count | |
| custom_conversion_count | |
| custom_conversion_amount | |
| custom_offline_conversion_count | |
| custom_offline_conversion_amount | |
| roas | |
| cpc | |
| cpm |
GET /v1/performances
Description
Required Scope: misc
Get all account performances
ResultList of performance records
Resulting Structure| performance_uid | Identifier for performance |
| account_id | |
| performance_name | |
| performance_date | |
| fb_ad_account_id | |
| metro_area | Venue metro area |
| creation_timestamp | |
| onsale_date | |
| venue_name | |
| display_venue_name | |
| promoter | |
| artist_name | |
| additional_artist_names | |
| campaign_event_key | |
| province | Venue Province |
| country_code | Venue Country Code |
| city | Venue City |
| performance_url | |
| status | |
| announce_date | |
| buying_group | |
| notes | |
| performance_group_name | |
| venue_uid | |
| business_id | |
| fb_event_id | |
| label_name | |
| is_valid_idol | Performance is associated with a valid idol in Tbits system |
| outlet | |
| vendor |
GET /v1/performances/<performance_uid>
Description
Required Scope: misc
Get single performance
ResultSingle performance records
Resulting Structure| performance_uid | Identifier for performance |
| account_id | |
| performance_name | |
| performance_date | |
| fb_ad_account_id | |
| metro_area | Venue metro area |
| creation_timestamp | |
| onsale_date | |
| venue_name | |
| display_venue_name | |
| promoter | |
| artist_name | |
| additional_artist_names | |
| campaign_event_key | |
| province | Venue Province |
| country_code | Venue Country Code |
| city | Venue City |
| performance_url | |
| status | |
| announce_date | |
| buying_group | |
| notes | |
| performance_group_name | |
| venue_uid | |
| business_id | |
| fb_event_id | |
| label_name | |
| is_valid_idol | Performance is associated with a valid idol in Tbits system |
| outlet | |
| vendor |
POST /v1/performances
Description
Required Scope: misc
Create a new performance. Take note that this endpoint does not require a secret key unlike other endpoints for performances.
Input Parameters| performance_name * | |
| performance_date * | Format YYYY-MM-DD |
| onsale_date | Format YYYY-MM-DD |
| announce_date | Format YYYY-MM-DD |
| fb_ad_account_id | |
| venue_uid | |
| promoter | |
| artist_name | |
| campaign_event_key | |
| performance_url | Must begin with https:// |
| status | draft, ready, or archived |
| buying_group | Under 32 characters |
| notes | |
| performance_group_name | Under 128 characters |
| business_id | |
| fb_event_id | |
| label_name | |
| additional_artist_names | List of strings |
| outlet | |
| vendor |
New performance record
Resulting Structure| performance_uid | Identifier for performance |
| account_id | |
| performance_name | |
| performance_date | |
| fb_ad_account_id | |
| metro_area | Venue metro area |
| creation_timestamp | |
| onsale_date | |
| venue_name | |
| display_venue_name | |
| promoter | |
| artist_name | |
| additional_artist_names | |
| campaign_event_key | |
| province | Venue Province |
| country_code | Venue Country Code |
| city | Venue City |
| performance_url | |
| status | |
| announce_date | |
| buying_group | |
| notes | |
| performance_group_name | |
| venue_uid | |
| business_id | |
| fb_event_id | |
| label_name | |
| is_valid_idol | Performance is associated with a valid idol in Tbits system |
| outlet | |
| vendor |
POST /v1/performances/<performance_uid>
Description
Required Scope: misc
Update performance
Input Parameters| performance_name * | |
| performance_date * | Format YYYY-MM-DD |
| onsale_date | Format YYYY-MM-DD |
| announce_date | Format YYYY-MM-DD |
| fb_ad_account_id | |
| venue_uid | |
| promoter | |
| artist_name | |
| campaign_event_key | |
| performance_url | Must begin with https:// |
| status | draft, ready, or archived |
| buying_group | Under 32 characters |
| notes | |
| performance_group_name | Under 128 characters |
| business_id | |
| fb_event_id | |
| label_name | |
| additional_artist_names | List of strings |
Updated performance record
Resulting Structure| performance_uid | Identifier for performance |
| account_id | |
| performance_name | |
| performance_date | |
| fb_ad_account_id | |
| metro_area | Venue metro area |
| creation_timestamp | |
| onsale_date | |
| venue_name | |
| display_venue_name | |
| promoter | |
| artist_name | |
| additional_artist_names | |
| campaign_event_key | |
| province | Venue Province |
| country_code | Venue Country Code |
| city | Venue City |
| performance_url | |
| status | |
| announce_date | |
| buying_group | |
| notes | |
| performance_group_name | |
| venue_uid | |
| business_id | |
| fb_event_id | |
| label_name | |
| is_valid_idol | Performance is associated with a valid idol in Tbits system |
DELETE /v1/performances/<performance_uid>
Description
Required Scope: misc
Delete performance
ResultEmpty object
GET /v1/template_portals
Description
Required Scope: misc
Get account template portals
ResultTemplate portal record(s)
Resulting Structure| portal_uid | |
| account_id | |
| portal_name | |
| performance_group_name | |
| password | |
| templates_created | Number of templates created |
| creation_timestamp | |
| last_access_timestamp |
GET /v1/template_portals/<portal_uid>
Description
Required Scope: misc
Get single template portal
ResultTemplate portal record
Resulting Structure| portal_uid | |
| account_id | |
| portal_name | |
| performance_group_name | |
| password | |
| templates_created | Number of templates created |
| creation_timestamp | |
| last_access_timestamp |
POST /v1/template_portals
Description
Required Scope: misc
Create template portal
Input Parameters| portal_name * | |
| performance_group_name * | |
| password | Including will require the given password when accessing the portal |
New template portal record
Resulting Structure| portal_uid | |
| account_id | |
| portal_name | |
| performance_group_name | |
| password | |
| templates_created | Number of templates created |
| creation_timestamp | |
| last_access_timestamp |
POST /v1/template_portals/<portal_uid>
Description
Required Scope: misc
Update template portal
Input Parameters| portal_name * | |
| performance_group_name * | |
| password | Including will require the given password when accessing the portal |
Updated template portal record
Resulting Structure| portal_uid | |
| account_id | |
| portal_name | |
| performance_group_name | |
| password | |
| templates_created | Number of templates created |
| creation_timestamp | |
| last_access_timestamp |
DELETE /v1/template_portals/<portal_uid>
Description
Required Scope: misc
Delete template portal
ResultEmpty object
Apps Calls
GET /v1/apps/<page_tab_id>/leaderboard
Description
Required Scope: apps
Get a Public Leaderboard
Input Parameters| session_uid | A valid session identifier for logged in user. Required for friends_only = true |
| friends_only | Only return leaderboard info for friends of the logged in user |
An array of following rows
Resulting Structure| fan_id | |
| display_name | |
| correct_answer_count | |
| points | |
| clicker_points |
GET /v1/apps
Description
Required Scope: apps
Get a list of campaigns on the account
Input Parameters| app_type | Limit Results to specific type |
| is_scheduled | Whether or not campaign is included into scheduler |
| business_id | Limit request to specific business |
An array of structures with following fields
Resulting Structure| page_tab_id | |
| name | |
| app_type | |
| creation_timestamp | |
| live_status | |
| business_id | |
| is_scheduled | |
| is_active | |
| media_map | |
| timezone | |
| props | |
| locale_props | |
| style_props | |
| links_map |
GET /v1/businesses
Description
Required Scope: apps
Get a list of businesses on the account
ResultAn array of structures with following fields
Resulting Structure| legal_rules | |
| legal_terms | |
| legal_privacy | |
| business_id | |
| business_name | |
| media_map | |
| scheduler_props | |
| locale_props | |
| style_props |
GET /v1/businesses/<business_id>
Description
Required Scope: apps
Get a specific Business record given ID
Resultstructure with following fields
Resulting Structure| legal_rules | |
| legal_terms | |
| legal_privacy | |
| business_id | |
| business_name | |
| media_map | |
| scheduler_props | |
| locale_props | |
| style_props |
GET /v1/apps/<page_tab_id>/bundle_stats
Description
Required Scope: apps
Obtain statistical data for a specific bundle campaign
Input Parameters| start_date | Date filter for stats |
| end_date | Date filter for stats |
A structure with following keys
Resulting Structure| summary | A dictionary of summary data for all campaigns included in the bundle with keys [start_date, end_date, total_views, total_shares, total_entries, total_optins] |
| bundles | A list of dictionaries representing all campaigns included in the bundle with keys [name, page_tab_id, views, shares, entries, opt_ins, max_views |
GET /v1/apps/<page_tab_id>/stats
Description
Required Scope: apps
Obtain statistical data on executed campaign
Input Parameters| start_date | Date filter for stats |
| end_date | Date filter for stats |
A structure with following fields
Resulting Structure| page_tab_id | |
| name | |
| total_entries | |
| fan_count | |
| view_count | |
| unique_view_count | |
| subscribers | Number of unique fans who subscribe to at least one of phone or email |
| phone_subscribers | Number of phone subscribers |
| email_subscribers | Number of email subscribers |
GET /v1/apps/<page_tab_id>/detailed_stats
Description
Required Scope: apps
Fetch detailed stats for a campaign
Input Parameters| target * | One of leaderboard, fan_points, quiz_results, clicker_results, chat_history, overlay_timeline, feed_switching, websocket_connections,websocket_raw_connections,wager_points |
| start_timestamp | Date filter |
| end_timestamp | Date filter |
| tab_item_id | Filter to specific tab items for target = wager_points |
Array of objects depending on your requested target
GET /v1/apps/<page_tab_id>/props
Description
Required Scope: apps
Get all props for a specific page tab
ResultA structure of campaign props with configured attributes
GET /v1/apps/<page_tab_id>
Description
Required Scope: apps
Fetch configuration of existing campaign for custom visual or other purposes
Input Parameters| include_details | Boolean value to include details like quiz questions/tab items/etc. |
A structure of campaign with configured attributes
GET /v1/apps/<page_tab_id>/total_points
Description
Required Scope: apps
Fetch total fan points for a campaign
Input Parameters| start_timestamp | Date filter |
| end_timestamp | Date filter |
A structure with following fields
Resulting Structure| total_points |
GET /v1/apps/<page_tab_id>/wager_entries
Description
Required Scope: apps
Fetch entries for a wager campaign
Input Parameters| q | Query string |
| start_date | Date filter |
| end_date | Date filter |
An array of Structures with following fields
Resulting Structure| tab_item_id | |
| page_tab_id | |
| creation_date | |
| title | |
| subtitle | |
| description | |
| tag_id | |
| tag_name | |
| position | |
| active_date | |
| props | |
| inventory_count | |
| item_count | |
| item_group_name | |
| activation_timestamp | |
| price | |
| media_uid | |
| items_purchased | |
| latitude | |
| longitude | |
| media_map | |
| wagers |
GET /v1/apps/<page_tab_id>/simple_points
Description
Required Scope: apps
Fetch fan points for a campaign without any PII
Input Parameters| start_timestamp | Date filter |
| end_timestamp | Date filter |
A structure with following fields
Resulting Structure| fan_id | |
| point_count | |
| creation_timestamp |
GET /v1/apps/<page_tab_id>/simple_activities
Description
Required Scope: apps
Fetch fan activities for a campaign without any PII
ResultA structure with following fields
Resulting Structure| fan_id | |
| activity_id | |
| creation_timestamp |
POST /v1/apps/<page_tab_id>/registration/checkin
Description
Required Scope: apps
Check-in Event Pass for Registration campaign.
Input Parameters| pass_code | 8 digit alphanumeric code. One of pass_code OR pass_uid required. |
| pass_uid | UUID. One of pass_code OR pass_uid required. |
An Event Pass object with following structure
Resulting Structure| pass_uid | |
| section_uid | |
| claim_fan_id | |
| fan_id | |
| transferee_email | |
| checked_in | |
| pass_code |
