The Prize Object

A Prize is the record you create when you want to award a prize (either an inventory item such as a concert ticket, or a cash prize) to a listener.

Prize Types

There are 3 types of Prize in Audata - Cash, Inventory, and List prizes. This is represented in the prize_type attribute of the Prize object.

  • Cash - a prize with a cash value.
  • Inventory - an inventory item (e.g. concert tickets, a gift card).
  • List - instead of winning a prize, the listener is added to a List (usually used to put listeners into a draw for a bigger prize down the track.
idintegerThe primary key for the record
listener_idinteger or nullThe ID of the Listener who has won the prize. This can be null before the listener has confirmed their details.
descriptionstringA description of the prize as a string.
phone_numberstringThe phone number of the prize winner in local format.
campaign_idintegerThe ID of the Campaign the Prize is attached to.
status_idintegerThe ID of the current Prize Status for the prize.
prize_typestringThe type of the prize as either "cash", "inventory" or "list".
cash_amountdecimalThe amount of cash won for cash prizes in the local currency.
inventory_item_idintegerFor inventory prizes, the ID of the Inventory Item that has been won.
inventory_qtyintegerFor inventory prizes, the quantity of the Inventory Item that has been won.
list_idintegerFor list prizes, the ID of the List that the winner will be added to.
show_idintegerThe ID of the Show that awarded the prize.
custom_dataobjectAn object with custom data submitted along with this prize.
valuedecimalThe total prize value in the default currency.
finance_dataobjectWhen Custom Finance Fields are enabled for an instance, a JSON object with the relevant finance coding data.
created_atstringThe time the record was created as a ISO 8601 string
updated_atstringThe last time the record was modified as a ISO 8601 string
confirmed_atstringThe time the record was confirmed as a ISO 8601 string
uuidstringThe UUID of the prize.

Awarding Prizes

Awarding Prizes without a Listener ID

You can award prizes without a Listener record and Audata will trigger the configured notification rules for your instance. Typically, and by default, Audata will send an SMS message to the prize winner with their redemption link and collect their details. Once the Listener has provided their details, the Prize will move to its Confirmed status, and an associated Listener record will be created for the Prize.

The below cURL request shows an example of creating a Prize without a Listener ID...

curl --request POST \
  --url \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"prize":{"phone_number":"0412123456","prize_type":"cash","cash_amount":"50.00"}}'

In the above example, we are awarding a cash prize of $50.00 (in local currency) to a specified phone number.

Awarding Prizes with a Listener ID

There are times you may not want to rely on the Audata Promo automation features, and instead provide the winner details yourself. For example, you may already have the winners information in some kind of local database, and you want to award them a prize using Audata. To do this, you simply create a Listener record, and then pass the listener_id parameter along with your Prize.

curl --request POST \
  --url \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"prize":{"listener_id":123,"prize_type":"inventory","inventory_item_id":12345,"inventory_qty":1}}'