Subiz API

Introduction

The Subiz API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

Here is how you use basic HTTP auth with curl:

curl https://api.subiz.com/v1/account \
   -u 'c0c7cd5f-3321-4302-983f-097928a860f2:'

If you need to authenticate via HTTP header, use -H 'api-key: c0c7cd5f-3321-4302-983f-097928a860f2' instead of -u 'c0c7cd5f-3321-4302-983f-097928a860f2:'.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Subiz uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a create failed, etc.), and codes in the 5xx range indicate an error with Subiz's servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully, we return a 402 error code.

HTTP status code summary

Code Description
200 - OK Everything worked as expected.
204 - No Content The request has been successfully processed, but there is nothing to return. It is often returned to a DELETE request.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 - Server Errors Something went wrong on Subiz's end.

Rate Limiting

The API may rate limit submission of requests for your application. Such limits are managed as an allowed number of requests per time window. In that case a '429 Too Many Requests' response code will be returned along with the following headers

  • X-RateLimit-Limit: The maximum number of requests that the client is permitted to make in this window.
  • X-RateLimit-Remaining: The number of requests allowed in the current window.
  • X-RateLimit-Reset: The time at which the current rate limit window will be reset as a Unix timestamp.

Rate limits are managed on a per App basis and may be adjusted based on system load. We ask that you pay attention to the rate limit - continuously breaking the rate limit may result in a lowered limit for your App or disabling API services.

Webhooks

What is a Webhook?

The concept of a WebHook is simple. A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST.

Webhooks allow you to build or set up integrations which subscribe to certain events on Subiz.com. When an event occurs, we'll send an HTTP POST request to the URL you've specified.

Events

The available events are:

Name Description
chat_ended Any time a Chat is ended
offline_message Any time an Offline message is sent

Event data

Here's an example of the JSON we will send you:

{
  "event_name": "chat_ended",
  "secret": "yoursecret",
  "data": {
    ...
  }
}

We will resend webhook notifications every hour for up to 24 hours until both of the following are true:

  • The webhook responds within 30 seconds
  • The webhook responds with a successful HTTP response code (200)