TalkBox Web Service API (1.0)

Description

This service allows clients to access their TalkBox data through a web service API. Clients can perform basic operations on their contact database such as reading, adding and editing of contacts and fields. Where possible the API adheres to REST standards.

Structured response data is in JSON format.

Authentication

Authentication is done with Basic HTTP Authentication as defined by W3C.

username

Your TalkBox account's API Username (see your API credentials).

password

The corresponding API Password.

The authentication does not persist, each request authenticates independently. Authentication failure will return HTTP status code 401.

API credentials can be managed through Talkbox by account owners. We encourage the use of expiring credentials and suggest having a unique credential for each Talkbox API integration you are using.

When creating new API credentials please make sure you copy the details when prompted, as they cannot be recovered after they are created.

Rate Limiting

The API tracks usage for each account, and will return HTTP status code 429 once an account records more than 10,000 request within an hour. The rate limit will reset every hour, on the hour (in UTC).

Resources

Note: For POST and PUT requests which accept JSON data, you must include the Content-Type: application/json header.

Usage

Account

Get

You can retrieve account information by issuing an HTTP GET request to /account.

If the get is successful you will be returned an object with the account's properties and most recent statistics as a response.

Example Request

Example Response

  {
    "created_at": "2015-01-20T09:41:04+11:00",

    // Business contact details for ImpactData
    "name": "The Pub On The Corner",
    "contact_name": "Barry O'Manager",
    "email": "[email protected]",
    "address": "PO Box 4556, Brunswick",
    "phone": "0423 456 789",

    // Business contact details for customers
    "street_address": "Cnr. High Street and Low Road",
    "suburb": "Brunswick",
    "postcode": "3056",
    "state": "VIC",
    "country": "Australia",
    "website": "http://www.tpotc.com.au",
    "public_email": "[email protected]",
    "public_phone": "03 9876 5432",

    "default_email_sender_detail_id": 123,
    "default_sms_sender_detail_id": 456,
    "auto_purchase_sms_credits_amount": 1000,
    "timezone": "Melbourne",
    "sms_credit_price_ex_tax": "$0.0750",

    // Account latest statistics
    "statistics_created_at": "2015-01-20T08:00:00+11:00",
    "last_login": 1,               // Days since last login
    "last_send": 5,                // Days since last send
    "contacts_count": 20431,
    "thirty_day_change": 512,      // Contacts joining the database in the last 30 days
    "eligible_email_count": 18457, // Contacts eligible to receive email
    "eligible_sms_count": 1275,    // Contacts eligible to receive SMS
    "forms": 3,                    // # of forms which the account is using
    "auto_comms": 2                // # of currently active automated communications
  }

Update

You can update the business contact details of the account by issuing an HTTP PUT request to /account with any of the following optional parameters:

If the update is successful you will get the an object representing the updated account as per GET /account above.

Example Request

{
  "website": "www.cornerpub.com",
  "public_email": "[email protected]"
}
        

Example Response

    {
      "created_at": "2015-01-20T09:41:04+11:00",
      "name": "The Pub On The Corner",
      "contact_name": "Barry O'Manager",
      "email": "[email protected]",
      "address": "PO Box 4556, Brunswick",
      "phone": "0423 456 789",

      "street_address": "Cnr. High Street and Low Road",
      "suburb": "Brunswick",
      "postcode": "3056",
      "state": "VIC",
      "country": "Australia",
      "website": "http://www.cornerpub.com",
      "public_email": "[email protected]",
      "public_phone": "03 9876 5432",

      "default_email_sender_detail_id": 123,
      "default_sms_sender_detail_id": 456,
      "auto_purchase_sms_credits_amount": 1000,
      "timezone": "Melbourne",
      "sms_credit_price_ex_tax": "$0.0750",

      "statistics_created_at": "2015-01-20T08:00:00+11:00",
      "last_login": 1,
      "last_send": 5,
      "contacts_count": 20431,
      "thirty_day_change": 512,
      "eligible_email_count": 18457,
      "eligible_sms_count": 1275,
      "forms": 3,
      "auto_comms": 2
    }

Fields

Get

You can retrieve the list of fields by issuing an HTTP GET request to /fields.

If the get is successful you will be returned a list of fields, each with their :system_name containing the field details as a response.

Example Request

Example Response

  {
    "first_name":
    {
      "field_type":"Text",
      "options":{},
      "name":"First name"
    },
    "last_name":
    {
      "field_type":"Text",
      "options":{},
      "name":"Surname"
    },
    "favourite_marx_bro":
    {
      "field_type":"MultipleChoice",
      "options":
      {
        "11":"Harpo",
        "12":"Zeppo",
        "9":"Chico",
        "10":"Groucho"
      },
      "name":"Favourite Marx Brother"
    },
    "email":{
      "field_type":"Text",
      "options":{},
      "name":"Email"
    }
  }

Create

You can create a field by issuing an HTTP POST request to /fields with the following parameters:

If the create is successful you will get the field :system_name containing the field details as a response.

Example Request

{
  "name": "A choice field",
  "field_type": "MultipleChoice",
  "options": [
    "The first one",
    "The middle one",
    "The last one"
  ]
}
        

Example Response

  {
    "a_choice_field":
      {
      "name":"A choice field",
      "field_type":"MultipleChoice",
      "options":
      {
        "51":"The first one",
        "52":"The middle one",
        "53":"The last one"
      }
    }
  }

Update

You can update a field by issuing an HTTP PUT request to /fields/:system_name with the following parameters:

NOTE: While options are not required for updates to SingleChoice and MultipleChoice fields, if any options are included, the full set of desired options is then also required. Any existing options not included in the options array will be destroyed from within the application.

If the update is successful you will get the field :system_name containing the field details as a response.

Example Request

{
  "name": "Which option are you interested in?",
  "options": [
    "The first one",
    "The last one",
    "Another one"
  ]
}
        

Example Response

  {
    "a_choice_field":
      {
      "name":"Which option are you interested in?",
      "field_type":"MultipleChoice",
      "options":
      {
        "51":"The first one",
        "53":"The last one",
        "67":"Another one"
      }
    }
  }

Delete

You can delete a field by issuing an HTTP DELETE request to /fields/:system_name or /fields/:id

NOTE: Cannot delete system field, required by account to function correctly.

Example Request

Example Response

  {
    "a_choice_field":
      {
      "name":"Which option are you interested in?",
      "field_type":"MultipleChoice",
      "options":
      {
        "51":"The first one",
        "53":"The last one",
        "67":"Another one"
      }
    }
  }

Contacts

NOTE:

Contacts in standard accounts require either a valid email address or mobile_number to be saved to the database, contacts in mirror mode accounts require an external_identifier.

Existing contact attributes cannot be removed via the API, they may only be updated (or added to in the case of 'MultipleChoice' fields).

Passwords may be set for contacts by assigning the password attribute.

Tags belonging to the contact are returned as part of a successful response along with contact attributes, but they can currently only be set via the Contacts in Tags endpoints

Version Tags

Version tags are contact meta information, differing from conventional tags and only appearing on the contact change log. As an array type they should not be represented as a string. And can be attributed to contact create and update actions. They are optional. For transparency reasons they are recommended, normally to represent the agent and/or source and/or reason of change.

Version tags are represented as normal data, of type array. Hence they are represented like the following:

json

{ ... ,"version_tags": ["bob", "pos", "user_request"] }

html form

... &version_tags[]=bob&version_tags[]=pos&version_tags[]=user_request& ...

url parameters

service/v1/contact/7?first_name=Marge&version_tags[]=bob&version_tags[]=pos&version_tags[]=user_request

Get one Contact

You can retrieve a single contact by issuing an HTTP GET request to /contact/:id.

If the get is successful it will return the contact's details as a response.

Example Request

Example Response

  {
    "id": 300,
    "first_name": "Barry",
    "last_name": "Hall",
    "email": "[email protected]",
    "favourite_marx_bro": [9,10],
    "tags": ["VIP","Gaming"]
  }

Get many Contacts

You can retrieve many contacts by issuing an HTTP GET request to /contact. The results are paginated, the default page size is 10 and the simplest valid querystring is page=1.

If the get request is successful it will return an array of contacts. The accepted parameters are as follows:

Note that all timestamps are in ISO-8601 format and that the contacts returned meet all criteria.

Example Request

Example Response

  [
    {
      "id": 300,
      "first_name": "Barry",
      "last_name": "Hall",
      "email": "[email protected]",
      "favourite_marx_bro": [9,10],
      "tags": ["VIP","Gaming"]
    },
    {
      "id": 301,
      "first_name": "Barry",
      "last_name": "Other",
      "email": "[email protected]",
      "favourite_marx_bro": [11,12],
      "tags": ["Hates Archer"]
    }
  ]

  

Create

You can create a contact by issuing an HTTP POST request to /contact with the following parameters:

If the create is successful you will get the contact's details as a response.

Example Request

{
  "first_name": "Julia",
  "last_name": "Gillard",
  "email": "[email protected]"
}
        

Example Response

  {
    "id": 301,
    "first_name": "Julia",
    "last_name": "Gillard",
    "email": "[email protected]",
    "favourite_marx_bro": [],
    "tags": []
  }

Update

You can update a contact by issuing an HTTP PUT request to /contact/:id with the following parameters:

If the update is successful you will get the contact's details as a response.

Example Request

{
  "email": "[email protected]",
  "favourite_marx_bro": [
    10,
    11
  ],
  "weekly_spend": 27.18,
  "unreachable_mobile": false
}
        

Example Response

  {
    "id": 300,
    "first_name": "Barry",
    "last_name": "Hall",
    "email": "[email protected]",
    "favourite_marx_bro": [9,10,11],
    "tags": ["VIP","Gaming"]
  }

Delete

You can delete a contact by issuing an HTTP DELETE request to /contact/:id

Example Request

Example Response

  {
    "id": 300,
    "first_name": "Barry",
    "last_name": "Hall",
    "email": "[email protected]",
    "favourite_marx_bro": [9,10,11],
    "tags": ["VIP","Gaming"],
    "deleted": true
  }
  

Create or Update

You can update an existing contact if a duplicate is found or create a new contact if one is not by issuing an HTTP POST request to /contact/create_or_update with the following parameters:

If the create or update is successful you will get the contact's details as a response.

NOTE: A duplicate is defined here as an email or mobile number match.

Example Request

{
  "first_name": "J",
  "last_name": "Gillard",
  "email": "[email protected]",
  "favourite_marx_bro": [
    9,
    10
  ]
}
        

Example Response

  {
    "id": 301,
    "first_name": "J",
    "last_name": "Gillard",
    "email": "[email protected]",
    "favourite_marx_bro": [9,10],
    "tags": []
  }

Find First

You can find the first contact that matches any text field, including email, mobile number or external_identifier by sending a HTTP GET request to /contact/find_first with the following parameters:

If the get is successful you will be returned the found contact's details as a response.

Example Request

Example Response

  {
    "id": 301,
    "first_name": "Julia",
    "last_name": "Gillard",
    "email": "[email protected]",
    "favourite_marx_bro": [],
    "tags": []
  }

Request Email Resubscription

You can request to send a resubscription email for a contact whose email address is unsubscribed by sending a HTTP POST request to /contact/:id/send_resubscription_email . An email is triggered to go out to the contact's email with a link to resubscribe their email address.

Example Request

Example Response

  {
    'message'=>'success'
  }

Request Mobile Resubscription

You can request to send a resubscription sms for a contact whose mobile number is unsubscribed by sending a HTTP POST request to /contact/:id/send_resubscription_sms . A sms is triggered to go out to the contact's mobile with a link to resubscribe their mobile number.

Example Request

Example Response

  {
    'message'=>'success'
  }

Segments

The use of the segments API is deprecated. Please use the Tags API instead

Tags

NOTE: Individual contacts' tags are also returned in the response of successful requests to the Contacts endpoints which return individual contacts.

Get

You can retrieve the list of tags by issuing an HTTP GET request to /tags.

If the get is successful you will be returned a list of tags as a response.

Example Request

Example Response

  [
    {
      "id": 38,
      "name": "Drinks Survey"
    },
    {
      "id": 51,
      "name": "Eligible for rides"
    }
  ]
  

You can retrieve the details of a tag by issuing an HTTP GET request to /tags/:id.

If the get is successful you will be returned the tag's details as a response.

Example Request

Example Response

  {
    "id": 38,
    "name": "Drinks Survey"
  }
  

Create

You can create a tag by issuing an HTTP POST request to /tags with the following parameters:

Example Request

{
  "name": "New tag via api"
}
        

Example Response

  {
    "id": 63,
    "name": "New tag via api"
  }
  

Update

You can update a tag by issuing an HTTP PUT request to /tags/:id with the following parameters:

NOTE: Existing tag will be overwritten with the given data.

If the update is successful an updated tag is returned as a response.

Example Request

{
  "name": "updated tag via api"
}
        

Example Response

  {
    "id": 50,
    "name": "updated tag via api"
  }
  

Delete

You can delete a tag by issuing an HTTP DELETE request to /tags/:id

Example Request

Example Response

  {
    "id": 52
    "name": "Does not exist any more",
    "deleted": true
  }
  

Untag Contacts

You can untag all contacts from a tag by issuing an HTTP PUT request to /tags/:id/untag_contacts

Example Request

Example Response

  {
    'message'=>'success'
  }
  

Contacts in Segments

The use of the segments contacts API is deprecated. Please use the Contacts in Tags API instead

Contacts in Tags

Get

You can retrieve the list of contacts in a tag by issuing an HTTP GET request to /tags/:id/contacts.

If the get is successful you will be returned a list of contacts, each with their :id as a response.

Example Request

Example Response

  {
    "id": [23,46,78,54]
  }
  

Create

You can add contacts to a tag by issuing an HTTP POST request to /tags/:id/contacts/:id

If the request is successful you will get a response with an empty body and an HTTP 200 code.

Example Request

Example Response

Delete

You can remove a contact from a tag by issuing an HTTP DELETE request to /tags/:id/contacts/:id

If the request is successful you will get a response with an empty body and an HTTP 200 code.

Example Request

Example Response

Subscriptions

NOTE:

You are not able to delete subscriptions, only querying for and creation of subscriptions are allowed.

If a subscription matches a contact, the contact id will be returned as part of the response.

Get many Subscriptions

You can retrieve many subscriptions by issuing an HTTP GET request to /subscriptions. The results are paginated, the default page size is 10 and the simplest valid querystring is page=1.

If the get request is successful it will return an array of subscriptions. The accepted parameters are as follows:

Note that all timestamps are in ISO-8601 format and that the contacts returned meet all criteria.

Example Request

Example Response

  [
    {
      "id": 12345430,
      "contact_id": 132456789,
      "external_identifier": "321654987",
      "recipient_id": 23232323,
      "channel": "email",
      "subscribed": true,
      "destination": "[email protected]",
      "created_at": "2022-08-10T16:05:20+10:00"
    },
    {
      "id":  12345432,
      "contact_id": 98765678,
      "external_identifier": "012345678",
      "recipient_id": 56565656,
      "channel": "mobile_number",
      "subscribed": false,
      "destination": "61412345678",
      "created_at": "2022-09-22T12:09:22+10:00"
    }
  ]

  

Create

You can create an unsubscription by issuing an HTTP POST request to /unsubscriptions with the following parameters:

Example Request

{
  "channel": "email",
  "contact_info": "[email protected]"
}
        

Example Response

  {
    "channel": "email",
    "contact_info": "[email protected]",
    "contact_id": null,
    "source": "api"
  }
  

Promotions

Create

You can create an email and/or SMS promotion which will send to a specified set of contacts by issuing an HTTP POST request to /promotions with the following parameters:

"date_trigger": {
  "field": "next_appointment",
  "offset_value": 3,
  "offset_period": "days",
  "offset_tense": "away",
  "hour": 15,
  "minute": 50,
  "only_nth_anniversary": 0
}
                

"date_trigger": {
  "field": "last_visit",
  "offset_value": 1,
  "offset_period": "month",
  "offset_tense": "ago",
  "hour": 13,
  "minute": 0,
  "only_nth_anniversary": 0
  "tags": "Inner-city"
}
                

"date_trigger": {
  "field": "date_of_birth",
  "offset_value": 2,
  "offset_period": "weeks",
  "offset_tense": "away",
  "hour": 10,
  "minute": 0,
  "only_nth_anniversary": 21
}
                

"date_trigger": {
  "field": "date_of_birth",
  "offset_value": 2,
  "offset_period": "weeks",
  "offset_tense": "away",
  "hour": 10,
  "minute": 0
}
                

NOTE:

Example Request

{
  "name": "What's on this week",
  "content": "<!DOCTYPE html><html><body><h1>A heading</h1><a href=\"www.google.com\">Google it!</a><img src=\"http://an-image.jpg\"><p>A paragraph.</p></body></html>",
  "recipient_details": "[email protected], [email protected]",
  "send_time": "2014-12-11 12:34"
}
        

Example Response

  {
    "id": 123,
    "name": "What's on this week",
    "recipient_count": 10,
    "email_recipients": 10,
    "sms_recipients": 10,
    "send_time": "2014-12-11T12:34:00Z",
    "date_trigger": null
  }
  

Update

You can update a promotion by issuing an HTTP PUT request to /promotions/:id with the same parameters as creating a promotion.

NOTE: if send_time or date_trigger is omitted, the promotion will not be sent immediately, unlike creating a promotion.

Example Request

{
  "sms_body": "Rescheduling this promotion",
  "send_time": "2015-10-21 07:28"
}
        

Example Response

  {
    "id": 123,
    "name": "Rescheduling this promotion",
    "recipient_count": 10,
    "email_recipients": 10,
    "sms_recipients": 10,
    "send_time": "2015-10-21T07:28:00Z",
    "date_trigger": null
  }
  

Delete

You can delete a promotion by issuing an HTTP DELETE request to /promotions/:id

Example Request

Example Response

  {
    "id": 123,
    "name": "What's on this week",
    "recipient_count": 10,
    "email_recipients": 10,
    "sms_recipients": 10,
    "send_time": "2014-12-11T12:34:00Z",
    "date_trigger": null
  }
  

Communications

Get

You can retrieve the list of communications sent from an account by issuing an HTTP GET request to /communications.

If the get is successful, an array of summary details for each communication is returned, with 10 entries per page. Additional pages of results can be obtained with the ?page= parameter.

Example Request

Example Response

  [
    {
      "id": 10567123,
      "name": "Friday Night Funk",
      "promotion_id": 10023789,
      "send_time": "2015-01-16T12:52:45+11:00",
      "channels": ["Email", "Sms"],
      "email_recipients": 1256,
      "email_opens": 332,
      "email_bounces": 5,
      "email_clicks": 100, // number of recipients who click at least one link
      "sms_recipients": 505,
      "flyer_url": "sbx.cc/fl73r",
      "thumbnail_url": null // the attribute has been discontinued
    },
    {
      "id": 10567456,
      "name": "Saturday Night Soul",
      "promotion_id": 10024725,
      "send_time": "2015-01-19T17:30:00+11:00",
      "channels": ["Sms"],
      "sms_recipients": 976,
      "thumbnail_url": null // the attribute has been discontinued
    }
  ]

Get for Promotion

You can retrieve the list of communications created from a given promotion by issuing an HTTP GET request to /promotions/:id/communications.

If the get is successful, an array of summary details for each communication is returned, with 10 entries per page. Additional pages of results can be obtained with the ?page= parameter.

Example Request

Example Response

  [
    {
      "id": 10567890,
      "name": "Friday Night Funk",
      "promotion_id": 10023789,
      "send_time": "2015-01-16T12:52:45+11:00",
      "channels": ["Email", "Sms"],
      "email_recipients": 1256,
      "email_opens": 332,
      "email_bounces": 5,
      "email_clicks": 100, // number of recipients who click at least one link
      "sms_recipients": 505,
      "flyer_url": "sbx.cc/fl73r",
      "thumbnail_url": null // the attribute has been discontinued
    },
  ]

Create

API Triggered Promotions are composed and saved in the TalkBox web application (navigate to Automated > API triggered). These can then be sent on demand to individual recipients using the API by creating a communication that references the promotion (communications are sent instances of a promotion). The promotion is referenced either by its id or system_name.

The API call is a POST request of the form:

where :identifier is either the id or system_name of the API triggered promotion.

The method accepts the following parameters:

If the request is successful you will receive the created communication data in the response.

NOTE:

API Triggered promotions must be set to active, If an API Triggered promotion is disabled, the request will fail and no communication will be created.

Example Request

{
  "contact_ids": "9591062,9591063,9591065"
}
        

Example Response

  {
    "id": 10567890,
    "name": "API-Triggered",
    "promotion_id": 10123456,
    "send_time": "2015-01-16T12:52:45+11:00",
    "channels": ["Email", "Sms"],
    "email_recipients": 0, // recipients can take a short period to generate, query using 'GET /communications/:id' for live data
    "email_opens": 0,
    "email_bounces": 0,
    "email_clicks": 0,
    "sms_recipients": 0,
    "flyer_url": "sbx.cc/fl73r",
    "thumbnail_url": null // the attribute has been discontinued
  }
  

Email Sender Details

Get

You can retrieve the list of email sender details by issuing an HTTP GET request to /email_sender_details.

If the get is successful you will be returned a list of email sender details as a response.

Example Request

Example Response

   [
     {
       "id": 123,
       "name": "The Pub On The Corner",
       "address": "[email protected]"
     },
     {
       "id": 456,
       "name": "Bands At The Pub On The Corner",
       "address": "[email protected]"
     },
   ]

Create

You can create an email sender detail by issuing an HTTP POST request to /email_sender_details with the following parameters:

If the create is successful you will get the newly created email sender detail as a response.

Example Request

{
  "name": "The Restaurant At The Pub On The Corner",
  "address": "[email protected]"
}
         

Example Response

   {
     "id": 789,
     "name": "The Restaurant At The Pub On The Corner",
     "address": "[email protected]"
   }

Update

You can update an email sender detail by issuing an HTTP PUT request to /email_sender_details/:id with the following parameters:

Example Request

{
  "name": "The Bistro At The Pub On The Corner",
  "address": "[email protected]"
}
         

Example Response

   {
     "id": 789,
     "name": "The Bistro At The Pub On The Corner",
     "address": "[email protected]"
   }

Delete

You can delete an email sender detail by issuing an HTTP DELETE request to /email_sender_details/:id

Example Request

Example Response

    {
      "id": 789,
      "name": "The Bistro At The Pub On The Corner",
      "address": "[email protected]"
    }

Editor

Get

You can establish a drag and drop (block) editor session by issuing an HTTP GET request to /editors/block/session.

If the get is successful a session key will be returned with which to access the editor at /editors/block. It is expected that the key will be used immediately, but it will be valid for access to the editor for up to 5 minutes from the moment of issue.

The parameters to this call are mostly URLs for an app or apps which are expected to work with TalkBox in supplying certain data necessary for the editor and receiving data when the editor session is concluded. At a minimum, the app or apps are expected to be able to receive the JSON structure which the editor generates. They may optionally also store autosave data, serve a set of templates for the editor to use, and manage metadata for images uploaded to the editor.

Modern browsers subject this kind of cross-domain communication (i.e. between TalkBox and other apps) to security restrictions. In order that the app or apps may communicate with TalkBox without restrictions, the app or apps must implement Cross-origin resource sharing, or CORS, allowing themselves to receive PUT, POST and GET calls from the origin URLs used by TalkBox. An example of a CORS setup giving TalkBox all required access to a Ruby on Rails app can be found here.

Example Request

Example Response

2--eyJhY2NvdW50X2lkIjoyLCJleHBpcmVzX2F0IjoiMjAxNS0wMS0yMlQwNTowODozMFoifQ==--2df3e71e2a8162132a66ea3b20cf59b2bb2e9131

Recipients

Prospective counts

You can get prospective recipient counts for a send by making a HTTP GET request to /recipients. You can optionally provide any of sms_body, filter_criteria or preferred_channel, all of which will be considered when calculating the prospective recipients. The data returned is the recipient counts for the given criteria if it was sent now.

Example Request

{
  "sms_body": "Hello [first name]!",
  "filter_criteria": [
    {
      "logical_operator": "AND",
      "field_name": "age",
      "operator": "<",
      "value": 30
    }
  ],
  "preferred_channel": "sms"
}
      

Example Response

{
    "total": 5,
    "email": 5,
    "sms": 2,
    "both": 2,
    "sms_cost": "0.16",
    "sms_parts": 2
}

Surveys

Survey responses

You can get all survey responses by making a HTTP GET request to /surveys. You can optionally provide from and to parameters with UTC timestamps to only select survey responses from that time range.

Example Request

Example Response

[
  {
    "id": 1,
    "contact_id": 123,
    "score": 9,
    "comments": "A+++ would survey again",
    "created_at": "2015-01-18T09:26:11+10:00"
  }
]

Net Promoter Score

You can get the total Net Promoter Score by making a HTTP GET request to /surveys/score. You can optionally provide from and to parameters with UTC timestamps to only calculate the Net Promoter Score from that time range of surveys.

Example Request

Example Response

{
  "score": 100
}

Templates

Get

You can retrieve the list of account-specific templates by issuing an HTTP GET request to /templates.

If the get is successful you will be returned a list of templates as a response.

Example Request

Example Response

  [
    {
      "id": 1067046281,
      "name": "My account-specific template",
      "structure": "{\r\n ... \r\n}",
      "enabled": true
    },
    {
      "id": 1067046282,
      "name": "Custom template",
      "structure": "{\r\n ... \r\n}",
      "enabled": true
    }
  ]

Show

You can retrieve data for a single account-specific templates by issuing an HTTP GET request to /templates/:id.

If the get is successful you will be returned the data for that template.

Example Request

Example Response

    {
      "id": 12345,
      "name": "My account-specific template",
      "structure": "{\r\n ... \r\n}",
      "enabled": true
    }
  

Create

You can create an account-specific template by issuing an HTTP POST request to /templates with the following parameters:

If the create is successful you will get the newly created template as a response.

Example Request

{
  "template": {
    "name": "New Template",
    "structure": "{...}",
    "enabled": true
  }
}
        

Example Response

  {
    "id": 12345,
    "name": "New template",
    "structure": "{...}",
    "enabled": true
  }

Update

You can update an account-specific template by issuing an HTTP PUT request to /templates/:id with the following parameters:

Example Request

{
  "template": {
    "name": "Updated Template",
    "structure": "{...}",
    "enabled": true
  }
}
        

Example Response

  {
    "id": 12345,
    "name": "Updated Template",
    "structure": "{...}",
    "enabled": true
  }

Delete

You can delete an account-specific template by issuing an HTTP DELETE request to /templates/:id

Example Request

Example Response

  {
    "id": 12345,
    "name": "Updated Template",
    "structure": "{...}",
    "enabled": true
  }

Vouchers

Vouchers

You can get all a contact's vouchers by making a HTTP GET request to /contacts/:id/vouchers.

Accepts an optional status parameter, with the values described here.

Example Request

Example Response

[
  {
    "name": "Free Pie",
    "description": "Footscray store only",
    "created_at": "2016-07-08T13:45:55+10:00",
    "redeemed_at": null,
    "valid_to": null,
    "valid_from": null,
    "expires_at": "2016-08-09T00:00:00+10:00",
    "user_data": {},
    "status": "redeemable",
    "url": "https://talkbox.impactapp.com.au/recipients/XSVHnlA_aF4BDVX8NZgKXg==/offers/QseVAyfXIGCk4Hk44GKd3A==/voucher",
    "contact_id": 1,
    "communication_id": 2,
    "promotion_id": 3,
    "external_identifier": "abc123"
  },
  {
    "name": "50% Off Pasties",
    "description": "All stores, weekdays only",
    "created_at": "2016-01-27T15:26:31+10:00",
    "redeemed_at": "2016-07-09T12:30:15+10:00",
    "valid_to": null,
    "valid_from": null,
    "expires_at": null,
    "user_data": {},
    "status": "redeemed",
    "url": "https://talkbox.impactapp.com.au/recipients/dMsECeXFa3zNrF4DUVq6Tw==/offers/dMsECeXFa3zNrF4DUVq6Tw==/voucher",
    "contact_id": 1,
    "communication_id": 2,
    "promotion_id": 3,
    "external_identifier": "abc123"
  }
]

Vouchers

You can find vouchers and associated contacts in one easy request using a HTTP GET request to /vouchers.

Parameters

Example Request

Example Response

[
    {
      "name": "Free Pie",
      "description": "Footscray store only",
      "created_at": "2016-07-08T13:45:55+10:00",
      "redeemed_at": null,
      "valid_to": null,
      "valid_from": null,
      "expires_at": "2016-08-09T00:00:00+10:00",
      "user_data": {},
      "status": "redeemable",
      "url": "https://talkbox.impactapp.com.au/recipients/XSVHnlA_aF4BDVX8NZgKXg==/offers/QseVAyfXIGCk4Hk44GKd3A==/voucher",
      "contact_id": 1,
      "communication_id": 2,
      "promotion_id": 3,
      "external_identifier": "abc123"
    },
    {
      "name": "50% Off Pasties",
      "description": "All stores, weekdays only",
      "created_at": "2016-01-27T15:26:31+10:00",
      "redeemed_at": "2016-07-09T12:30:15+10:00",
      "valid_to": null,
      "valid_from": null,
      "expires_at": null,
      "user_data": {},
      "status": "redeemed",
      "url": "https://talkbox.impactapp.com.au/recipients/dMsECeXFa3zNrF4DUVq6Tw==/offers/dMsECeXFa3zNrF4DUVq6Tw==/voucher",
      "contact_id": 1,
      "communication_id": 2,
      "promotion_id": 3,
      "external_identifier": "abc123"
    }
  ]

You can retrieve a voucher by issuing a HTTP GET request to /voucher/:id.

For string vouchers, the string_id is also acceptable.

Example Request

Example Response

{
  "name": "Free Pie",
  "description": "Footscray store only",
  "created_at": "2016-07-08T13:45:55+10:00",
  "redeemed_at": null,
  "valid_to": null,
  "valid_from": null,
  "expires_at": "2016-08-09T00:00:00+10:00",
  "user_data": {},
  "status": "redeemable",
  "url": "https://talkbox.impactapp.com.au/recipients/XSVHnlA_aF4BDVX8NZgKXg==/offers/QseVAyfXIGCk4Hk44GKd3A==/voucher",
  "contact_id": 1,
  "communication_id": 2,
  "promotion_id": 3,
  "external_identifier": "abc123"
}
  

You redeem a voucher by issuing a HTTP PUT request to /voucher/:id.

For string vouchers, the string_id is also acceptable.

Example Request

{
  "redeemed": true,
  "recipient_id": "dMsECeXFa3zNrF4DUVq6Tw=="
}
      

Example Response

{
  "name": "Free Pie",
  "description": "Footscray store only",
  "created_at": "2016-07-08T13:45:55+10:00",
  "redeemed_at": "2016-07-09T11:42:33+10:00",,
  "valid_to": null,
  "valid_from": null,
  "expires_at": "2016-08-09T00:00:00+10:00",
  "user_data": {},
  "status": "redeemed",
  "url": "https://talkbox.impactapp.com.au/recipients/XSVHnlA_aF4BDVX8NZgKXg==/offers/QseVAyfXIGCk4Hk44GKd3A==/voucher",
  "contact_id": 1,
  "communication_id": 2,
  "promotion_id": 3,
  "external_identifier": "abc123"
}
  

Offers

Get

You can retrieve the list of offers by issuing an HTTP GET request to /offers.

If the get is successful you will be returned a list of offers as a response.

Example Request

Example Response

  [
    {
      "id": 1,
      "name": "My custom voucher",
      "description": "Buy 1 Get 1 Free",
      "duration": null,
      "user_data": {},
      "created_at": "2016-07-12T14:28:51+10:00",
      "archived": false,
      "valid_from": null,
      "valid_to": "2018-05-04",
      "valid_from_datetime": null,
      "valid_to_datetime": "2018-05-04 00:00:00 +00:00",
      "reminder_message_ids": [],
      "expiry_message_id": null,
      "redemption_message_id": null,
      "creation_message_id": null,
      "provider": "talkbox",
      "restrict_days": null,
      "restrict_from_time": null,
      "restrict_to_time": null,
      "offer_type": "Promo Code"
    }
  ]
  

You can retrieve the details of an offer by issuing an HTTP GET request to /offers/:id.

If the get is successful you will be returned the offer's details and redemption statistics as a response.

Example Request

Example Response

  {
    "id": 1,
    "name": "My custom voucher",
    "description": "Buy 1 Get 1 Free",
    "duration": null,
    "user_data": {},
    "created_at": "2016-07-12T14:28:51+10:00",
    "archived": false,
    "valid_from": null,
    "valid_to": "2018-05-04",
    "valid_from_datetime": null,
    "valid_to_datetime": "2018-05-04 00:00:00 +00:00",
    "reminder_message_ids": [],
    "expiry_message_id": null,
    "redemption_message_id": null,
    "creation_message_id": null,
    "provider": "talkbox",
    "restrict_days": null,
    "restrict_from_time": null,
    "restrict_to_time": null,
    "offer_type": "Promo Code",
    "stats": {
      "total": 100,
      "redeemable": 50,
      "redeemed": 40,
      "unused": 10
    }
  }
  

Create

You can create an offer by issuing an HTTP POST request to /offers with the following parameters:

Example Request

{
    "offer": {
      "name": "API offer",
      "description": "Another offer",
      "duration": 10,
      "valid_from": null,
      "valid_to": null,
      "valid_from_datetime": "2022-09-13T10:42:03+10:00",
      "valid_to_datetime": "2023-09-13T10:42:03+10:00",
      "restrict_days": ["Thursday", "Friday", "Saturday"],
      "restrict_from_time": "12:05 AM",
      "restrict_to_time": "04:30 AM"
    }
  }

Example Response

  {
    "id": 1,
    "name": "API offer",
    "description": "Another offer",
    "duration": 10,
    "user_data": null,
    "created_at": "2025-08-13 20:50:18 +1000",
    "archived": false,
    "valid_from": "13/09/2022",
    "valid_to": "13/09/2023",
    "valid_from_datetime": "2022-09-13T10:42:03+10:00",
    "valid_to_datetime": "2023-09-13T10:42:03+10:00",
    "reminder_message_ids": [],
    "expiry_message_id": null,
    "redemption_message_id": null,
    "creation_message_id": null,
    "provider": "talkbox",
    "restrict_days": [
      "Thursday",
      "Friday",
      "Saturday"
    ],
    "restrict_from_time": "12:05 AM",
    "restrict_to_time": "04:30 AM",
    "offer_type": "Promo Code"
  }
  

Update

You can update an offer by issuing an HTTP PUT request to /offers/:id with the parameters used for POST.

If the update is successful an updated offer is returned as a response.

Example Request

{
  "offer": {
    "name": "updated offer",
    "archived": true
  }
}
        

Example Response

  {
    "id": 1,
    "name": "updated offer",
    "description": "Another offer",
    "duration": 10,
    "user_data": null,
    "created_at": "2025-08-13 20:50:18 +1000",
    "archived": true,
    "valid_from": "13/09/2022",
    "valid_to": "13/09/2023",
    "valid_from_datetime": "2022-09-13T10:42:03+10:00",
    "valid_to_datetime": "2023-09-13T10:42:03+10:00",
    "reminder_message_ids": [],
    "expiry_message_id": null,
    "redemption_message_id": null,
    "creation_message_id": null,
    "provider": "talkbox",
    "restrict_days": [
      "Thursday",
      "Friday",
      "Saturday"
    ],
    "restrict_from_time": "12:05 AM",
    "restrict_to_time": "04:30 AM",
    "offer_type": "Promo Code"
  }
  

Delete

You can delete an offer by issuing an HTTP DELETE request to /offers/:id

Example Request

Example Response

  {
    "id": 1,
    "name": "updated offer",
    "description": "Another offer",
    "duration": 10,
    "user_data": null,
    "created_at": "2025-08-13 20:50:18 +1000",
    "archived": true,
    "valid_from": "13/09/2022",
    "valid_to": "13/09/2023",
    "valid_from_datetime": "2022-09-13T10:42:03+10:00",
    "valid_to_datetime": "2023-09-13T10:42:03+10:00",
    "reminder_message_ids": [],
    "expiry_message_id": null,
    "redemption_message_id": null,
    "creation_message_id": null,
    "provider": "talkbox",
    "restrict_days": [
      "Thursday",
      "Friday",
      "Saturday"
    ],
    "restrict_from_time": "12:05 AM",
    "restrict_to_time": "04:30 AM",
    "offer_type": "Promo Code"
  }
  

Sections

Get

You can retrieve the list of sections by issuing an HTTP GET request to /sections.

If the get is successful you will be returned a list of sections as a response.

Example Request

Example Response

    [
      {
        "id": 1,
        "system_name": "promo_header",
        "created_at": "2020-10-30T08:55:32+11:00",
        "updated_at": "2020-10-30T08:56:02+11:00"
      },
      {
        "id": 2,
        "system_name": "promo_footer",
        "created_at": "2020-10-30T08:56:27+11:00",
        "updated_at": "2020-10-30T08:56:56+11:00"
      }
    ]
  

You can retrieve the details of a section by issuing an HTTP GET request to /sections/:id.

If the get is successful you will be returned the section's details as a response.

Example Request

Example Response

    {
      "id": 123,
      "system_name": "promo_header",
      "created_at": "2020-10-30T08:55:32+11:00",
      "updated_at": "2020-10-30T08:56:02+11:00",
      "structure": "{...}"
    }
  

Create

You can create a section by issuing an HTTP POST request to /sections with the following parameters:

Example Request

{
  "system_name": "survey_section",
  "structure": "..."
}
        

Example Response

    {
      "id": 4,
      "system_name": "survey_section",
      "created_at": "2020-10-30T08:55:32+11:00",
      "updated_at": "2020-10-30T08:56:02+11:00"
    }
  

Update

You can update a section by issuing an HTTP PUT request to /sections/:id with the parameters used for POST.

If the update is successful an updated section is returned as a response.

Example Request

{
  "system_name": "nps_section"
}
        

Example Response

  {
    "id": 4,
    "system_name": "nps_section",
    "created_at": "2020-10-32T08:55:32+11:00",
    "updated_at": "2020-10-32T08:56:02+11:00"
  }
  

Delete

You can delete a section by issuing an HTTP DELETE request to /sections/:id

Example Request

Example Response

    {
      "id": 4,
      "system_name": "nps_section",
      "created_at": "2020-10-32T08:55:32+11:00",
      "updated_at": "2020-10-32T08:56:02+11:00"
    }
  

Data formats

Notes

The preferred format of posting any array data is by separating the input values by commas. Posting array data in other forms may result in unknown consequences.

Example

array=element1,element1,element3

Field types

These are the different data types handled in the application for both fields and contacts:

JSON `structure` strings

Promotions, editors and templates expect their structure values to be a JSON string describing the document structure. These are not intended to be created or edited by hand, but are emitted by various API methods. These structure strings can be posted back to the TalkBox API anywhere an argument named structure is used.

Although these are not intended to be edited outside of TalkBox, below is an example JSON structure string that can be used for testing and verification.

{
  "version": 1,
  "document": {
    "block_type": "Global",
    "background_colour": "rgb(255, 255, 255)",
    "origin": {
      "template_id": 4,
      "name": "Left-hand column w/header",
      "editable": false,
      "loaded_at": "2016-01-04T02:02:26.835Z"
    },
    "layout": {
      "layout": [
        [
          {
            "id": "r0c0",
            "width": 600,
            "default_blocks": [
              "Heading"
            ]
          }
        ],
        [
          {
            "id": "r1c0",
            "width": 200,
            "default_blocks": [
              "Text"
            ]
          },
          {
            "id": "r1c1",
            "width": 400,
            "default_blocks": [
              "Image",
              "Text"
            ]
          }
        ]
      ]
    },
    "font": "Arial",
    "dimensions": {
      "width": 600,
      "height": 97
    },
    "page_colour": "rgb(241, 241, 241)",
    "text_colour": "rgb(44, 53, 57)",
    "responsive": true,
    "allow_responsive": true,
    "padding_top": 10,
    "padding_bottom": 10,
    "padding_left": 10,
    "padding_right": 10,
    "read_only": false,
    "block_guid": "editor_layout"
  },
  "regions": {
    "r0c0": {
      "blocks": [
        {
          "block_type": "Heading",
          "html": "<div style=\"text-align: center; font-size: 36px; font-family: Arial; font-weight: bold;\">Heading</div>",
          "padding_top": 10,
          "padding_bottom": 10,
          "padding_left": 10,
          "padding_right": 10,
          "read_only": false,
          "block_guid": "adf05e26-74f7-4238-b9e1-c74e3d1a2305"
        }
      ]
    },
    "r1c0": {
      "blocks": [
        {
          "block_type": "Text",
          "html": "Left column text",
          "padding_top": 10,
          "padding_bottom": 10,
          "padding_left": 10,
          "padding_right": 10,
          "read_only": false,
          "block_guid": "2850fda6-9df7-4b94-9683-f0804d03d929"
        }
      ]
    },
    "r1c1": {
      "blocks": [
        {
          "block_type": "Text",
          "html": "Right column text",
          "padding_top": 10,
          "padding_bottom": 10,
          "padding_left": 10,
          "padding_right": 10,
          "read_only": false,
          "block_guid": "9a886c8d-5431-40f0-b1ae-2cd1eee70f06"
        }
      ]
    }
  }
}
  

Errors

Standard HTTP status codes are used to indicate errors. There will usually be some additional information passed back in the body of the response.
In the case of 400 and 422 responses the body will contain one of the errors defined in the Custom Errors section below.

Requests that have been handled successfully return status code 200.

Custom Errors

These are passed back in the body of the response to provide additional information about some client errors (400, 422).
The errors are passed back as a two element JSON string of the form:

  {
    "code": 120,
    "description": "Email address is invalid"
  }