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.
Add Argument


                    

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

Result

Array 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

Result

Dictionary 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.
Result

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.
email
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
Result

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
Result

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
Result

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 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
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
Result

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
Result

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
Result

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
email
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
Result

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
email
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_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.
Result

Structure: {'meta': { 'min_fan_time_key':'xxx', 'max_fan_time_key':xxx, 'count':xxx }, 'data':[] }. Data is array with following elements

Resulting Structure
fan_id
email
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.
Result

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.
email 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.
Result

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.
Result

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.
email 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
email 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
Result

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

Resulting Structure
ticket_id Unique Identifier for the ticket
ticket_key Remote Tickey Key
account_id Tradable Bits Acount ID
email email on the ticket
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

Result

Single 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 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 *
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
Result

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/x-www-form-urlencoded

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
Result

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
Result

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
Result

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
Result

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
email 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
Result

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 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
Result

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.
Result

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
email
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.
email 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
Result

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
email
phone
user_key
network
idol_names Array of idol names to associate the fan with
is_explicit
Result

JSON object detailing created records

Resulting Structure
inserted JSON object with info on inserted records
count
info Array of fan_id, idol_uid for each inserted idol fan
errors Array of JSON objects detailing which rows failed insertion
idx Index of row with failed insertion
error Message outlining the reason the insertion was not successful
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 *
Result

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

Result

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
Result

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
Result

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

Result

Following structure

Resulting Structure
fan_id
account_id
name
first_name
last_name
display_name
is_confirmed
is_phone_confirmed
email
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
email
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.
Result

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

Result

Boolean 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

Result

Following structure

Resulting Structure
fan_point_uid
fan_id
point_uid
point_name
point_count
point_source
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 *
Result

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
Result

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.
Result

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
Result

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 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
Result

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
Result

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
Result

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'
Result

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 *
Result

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
Result

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
Result

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
Result

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
Result

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
Result

A point tier object

Resulting Structure
point_tier_uid
account_id
point_uid
point_name
tier_name
min_points
creation_timestamp

Ent Calls

GET /v1/ent/performances
Description

Required Scope: misc

Supported Content Types:

  • application/x-www-form-urlencoded

Get all account performances

Result

List 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
Result

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

Result

Single 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
Result

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

Result

Boolean 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
Result

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
performance_uid Optionally assign quest to a performance. Required when quest_type is scan or wristband, and when the reward_type is atvenu or bestring
target_page_tab_id
site_name
scan_group_names[]
link_url
quest_type * Must be one of 'scan', 'campaign', 'quickpicks', 'wristband', 'link_url', or 'custom'
is_required
fan_points_required Required when access_restriction_type is 'fan_points'
access_restriction_type Must be one of 'quests', 'fan_points', 'point_tier', or null
point_tier_uid point_tier_uid of a valid point tier. 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.
reward_type Optional. If included, must be one of 'atvenu', 'fan_points', 'bestring'
bestring_location_group_id
bestring_promotion_id
atvenu_sales_event_key
atvenu_promo_key
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
fan_points_reward
quest_title *
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.
Result

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

Result

HTTP 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.
Result

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'
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'.
Result

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

Result

HTTP 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.
Result

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
Result

Array of Idols Events and Array of Performances

Resulting Structure
idol_events Array of objects
idol_event_uid
performance_uid
creation_timestamp Absolute creation timestamp of the event
states Array of states for the event fan. Minimum 1, maximum 4. Can be one of 'saved', 'going', 'verified', 'attended', or 'collected'
creation_timestamp_iso ISO formatted creation timestamp of the event
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)
performances Array of objects
performance_uid
creation_timestamp Absolute creation timestamp of the performance
states Array of states for the performance fan. Minimum 1, maximum 3. Valid states are 'saved', 'going', 'verified', or 'registered'.
creation_timestamp_iso ISO formatted creation timestamp of the performance
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'].
Result

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
Result

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'].
Result

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
Result

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
Result

Resulting Structure
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
Result

Resulting Structure
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
Result

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.
Result

Resulting Structure
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
Result

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.

Result

The 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
Result

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

Resulting Structure
stream_key
feed_record_id
record_key
props
creation_timestamp
image_url
src_image_url
video_url
caption
network
record_url
latitude
longitude
links
link_url
link_name
author_id
author_user_key
author_screen_name
author_name
author_image_url
author_status
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
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
Result

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)
Result

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
Result

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
email One of phone or email are required
Result

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
email 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
Result

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
email
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
Result

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

Result

Record

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

Result

Following Structure

Resulting Structure
fan_id
account_id
name
first_name
last_name
display_name
is_confirmed
is_phone_confirmed
email
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
email
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
Result

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

Result

Following 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.
Result

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
Result

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

Result

A 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
Result

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.

Result

Array of JSON objects as per structure below

Resulting Structure
report_uid Identifier of the report
report_name Name of the report
report_type Type of the report. One of 'adwords_adaccount', 'app', '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.

Result

Structure: {'<report_type>': {}}. Corresponding object to the report's type is the data for the report, whose structure depends on the report's type. Below is structure for 'fb_adaccount' stats report.

Resulting Structure
spend Total spending
conversion Total sales value attributable to ads
offline_conversion Sales value attributable to offline conversion
conversion_count Number of sales
impressions Total number of impressions
reach Total number of unique people reached
frequency Average frequency per unique person
cpm Cost-per-thousand
cpa Cost-per-action
roi Return on investment rate
clicks Total number of clicks
ctr Clickthrough rate
cpc Cost-per-click

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"
Result

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.
Result

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

Result

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

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.
tracker_marketing_group_name Max length 64 characters
page_tab_id
Result

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.
Result

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
Result

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
Result

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 *
Result

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
Result

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
Result

A list of structures with the following fields

Resulting Structure
network Ad platform, e.g. facebook, twitter
ad_account_key
campaign_key
campaign_name
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/template_portals
Description

Required Scope: misc

Supported Content Types:

  • application/x-www-form-urlencoded

Get account template portals

Result

Template 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

Result

Template 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
Result

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
Result

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

Result

Boolean 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
Result

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
Result

An array of structures with following fields

Resulting Structure
page_tab_id
name
app_type
creation_timestamp
live_status
business_id
is_scheduled
is_active
media_map
timezone
props
locale_props
style_props
links_map
GET /v1/businesses
Description

Required Scope: apps

Supported Content Types:

  • application/x-www-form-urlencoded

Get a list of businesses on the account

Result

An array of structures with following fields

Resulting Structure
legal_rules
legal_terms
legal_privacy
business_id
business_name
media_map
scheduler_props
locale_props
GET /v1/businesses/<business_id>
Description

Required Scope: apps

Supported Content Types:

  • application/x-www-form-urlencoded

Get a specific Business record given ID

Result

structure with following fields

Resulting Structure
legal_rules
legal_terms
legal_privacy
business_id
business_name
media_map
scheduler_props
locale_props
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
Result

A structure with following keys

Resulting Structure
summary A dictionary of summary data for all campaigns included in the bundle with keys [start_date, end_date, total_views, total_shares, total_entries, total_optins]
bundles A list of dictionaries representing all campaigns included in the bundle with keys [name, page_tab_id, views, shares, entries, opt_ins, max_views
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
Result

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
Result

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

Result

A 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.
Result

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
Result

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
Result

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
Result

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

Result

A 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.
Result

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
Result

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
Result

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