APIs and Callbacks

Overview

API stands for Application Program Interface, and is a set of routines, protocols, and tools for building software applications.

API Call Structure

The call structure of the APIs is as follows:

Method: HTTP is the format used to enable communication between clients (like Web browsers) and servers. The most common methods are GET, POST, PUT and DELETE.
For more information on HTTP, see: HTTP Specification.
URL: The Web address. The URL host is the Vibes public API site.
Header: A unit of information that contains information about the file. Vibes APIs use a JSON file.
Body: Represents the body of the request or response and allows you to declare what the content type is and how it should be handled.

Topics in this Section

Rate Limiting

Vibes throttles the number of requests that can hit the APIs at one time. The rates are the following:

For inbound events:

300 requests/second

For all other company api calls (including mobile wallet updates)

100 requests/second

For mobile app calls

100 requests/second

For all other api calls

20 requests/second

NOTE: A “429 Too Many Requests” response will be sent in any cases where the number of requests hitting the API are over the defined rate limits.

Additional technical details are available here, including hosts, server end points, authentication, API details, IP addresses, and callback details.

API Version 1

This is the default version. It does not accept the international format, E.164 phone numbers.

Note: If you are using Version 1, you cannot use the E.164 format. If you do use it, you will get an error returned.

API Version 2

To fully serve its international customers, Vibes released Version 2 of the Vibes Mobile Engagement Platform APIs in 2016 to include support for international E.164 phone numbers.

Example API Version 1

POST
http://public-api.vibescm.com/companies/ABC123/campaigns/acquisition/abc123/participants/
Headers
Content-Type:
Application/JSON
Authorization:
Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
BODY
{
   "external_person_id":"EXT542342",
   "mobile_phone":{
      "mdn":"2995551234"
   },
   "custom_fields":{
      "first_name":"John",
      "last_name":"Doe"
   }
}

Example API Version 2 (E.164 MDN Format)

POST
http://public-api.vibescm.com/companies/ABC123/campaigns/acquisition/abc123/participants/
Headers
Content-Type:
Application/JSON
Authorization:
Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
BODY
{
   "external_person_id":"EXT542342",
   "mobile_phone":{
      "mdn":"+12995551234"
   },
   "custom_fields":{
      "first_name":"John",
      "last_name":"Doe"
   }
}

REST API Tree URI Structure

/companies
- /companies/:id
  - /companies/:company_key/mobiledb
    - /companies/:company_key/mobiledb/persons
      - /companies/:company_key/mobiledb/persons/:person_id
        /companies/:company_key/mobiledb/persons/:person_id/subscriptions
        /companies/:company_key/mobiledb/persons/:person_id/subscriptions/:subscription_list_id
    - /companies/:company_key/mobiledb/subscription_lists
      - /companies/:company_key/mobiledb/subscription_lists/:id
    - /companies/:company_key/mobiledb/broadcasts
      - /companies/:company_key/mobiledb/broadcasts/:broadcast_id
  - /companies/:company_key/campaigns
    - /companies/:company_key/campaigns/acquisition
      - /companies/:company_key/campaigns/acquisition/:id
        /companies/:company_key/campaigns/acquisition/:id/participants
    - /companies/:company_key/campaigns/wallet
      - /companies/:company_key/campaigns/wallet/:id
        /companies/:company_key/campaigns/wallet/:id/items
        /companies/:company_key/campaigns/wallet/:id/items/:item_id
        /companies/:company_key/campaigns/wallet/:id/messages
        /companies/:company_key/campaigns/wallet/:id/messages/:message_id
  - /companies/:company_key/incentives
    - /companies/:company_key/incentives/pools
      - /companies/:company_key/incentives/pools/:pool_id
        /companies/:company_key/incentives/pools/:pool_id/issuances
    - /companies/:company_key/incentives/codes
      - /companies/:company_key/incentives/codes/:code
        /companies/:company_key/incentives/codes/:code/issuances
        /companies/:company_key/incentives/codes/:code/redemptions
    /companies/:company_key/events
  - /companies/:company_key/config
    - /companies/:company_key/config/callbacks
      - /companies/:company_key/config/callbacks/:callback_id