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.


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

API Versions

There are currently two versions of the APIs available. You can see what version you are using by looking at the API header.

X-API-Version: 1



Topics in this Section


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_id/mobiledb
        • /companies/:company_id/mobiledb/persons
          • /companies/:company_id/mobiledb/persons/:person_id
            • /companies/:company_id/mobiledb/persons/:person_id/subscriptions
              • /companies/:company_id/mobiledb/persons/:person_id/subscriptions/:subscription_list_id
        • /companies/:company_id/mobiledb/subscription_lists
          • /companies/:company_id/mobiledb/subscription_lists/:id
        • /companies/:company_id/mobiledb/broadcasts
          • /companies/:company_id/mobiledb/broadcasts/:broadcast_id
      • /companies/:company_id/campaigns
        • /companies/:company_id/campaigns/acquisition
          • /companies/:company_id/campaigns/acquisition/:id
            • /companies/:company_id/campaigns/acquisition/:id/participants
        • /companies/:company_id/campaigns/wallet
          • /companies/:company_id/campaigns/wallet/:id
            • /companies/:company_id/campaigns/wallet/:id/items
              • /companies/:company_id/campaigns/wallet/:id/items/:item_id
            • /companies/:company_id/campaigns/wallet/:id/messages
              • /companies/:company_id/campaigns/wallet/:id/messages/:message_id
      • /companies/:company_id/incentives
        • /companies/:company_id/incentives/pools
          • /companies/:company_id/incentives/pools/:pool_id
            • /companies/:company_id/incentives/pools/:pool_id/issuances
        • /companies/:company_id/incentives/codes
          • /companies/:company_id/incentives/codes/:code
            • /companies/:company_id/incentives/codes/:code/issuances
            • /companies/:company_id/incentives/codes/:code/redemptions
        /companies/:company_id/events
      • /companies/:company_id/config
        • /companies/:company_id/config/callbacks
          • /companies/:company_id/config/callbacks/:callback_id