The following technical details are provided to help you better understand the Vibes APIs and Callbacks.

URL Host

The following is the standard Vibes URL host, which is the Vibes public API site.

Headers

All Vibes API calls are set up to receive data in a standard JSON format.

The following is the header to include on all API calls.

Content-Type: application/json
X-API-Version: 2

In addition, you will need to choose your authentication, which will also be included in the header.

Basic authentication

Basic Authentication is the simplest way to implement access controls. Most programming languages have built-in libraries to support Basic Authentication. The following is a brief description of how the header is constructed:

1. Combine the username and password into a "username:password" string.
2. Encode the resulting string using Base64.
3. Add the Authorization HTTP header and set the value to "Basic " plus the encoded string.

Notes

• Usernames should be different in the EU and US instances.
• Include the extra space after "Basic ".

For example, if the username is 'VibesUser' and the password is "Password123" then the header is as follows:

Authorization: Basic VmliZXNVc2VyOlBhc3N3b3JkMTIz

Client certification authentication

Vibes supports Client Certificate Authentication as an extra layer of security for API calls.

Error Handling and Responses

APIs follow standard HTTP Response codes. See individual API calls for errors that can be returned. Any 4XX error will return a JSON body with the specific information and code. The response will be an errors object, with an array of all the errors that occurred on the request, as shown in the following example.

{"errors": [
    {"message":"The MDN field is required","code":1},
    {"message":"The zip code must be numeric","code":2}
  ]
}

Rate Limiting

Vibes throttles the number of requests that can hit the APIs at one time per user. If the number of requests to Vibes' system from your endpoint is more than the rate limit, a “429 Too Many Requests” response will be sent.

The rates are the following:

• For inbound events: 300 requests/second
• All non-event API calls per company_key: 100 requests/second
• Non-event API calls per app_id: 100 requests/second
• Google Wallet updates: 20 requests/second