Integrate your product with Kounta

Kounta uses an OAuth 2.0 compliant RESTful API for easy integration with third-party applications.

API URLs

Kounta’s REST API is based at https://api.kounta.com/v1/. There is no unencrypted (non-SSL) version available.

Authentication

Two types of authentication are available:

Basic Access Authorization

Developers can use this method for the convenience of session-free testing.

To use Basic Access Authorization, send an Authorization header with each request with the client_id:client_secret string encoded in Base64. E.g.:

Authorization: Basic eHh4Onl5eQ==

Read this article for a detailed description of Basic Access Authorization.

OAuth 2.0

Production applications must use OAuth 2.0 for authentication.

OAuth 2.0 is a little complicated. Fortunately for you, there are plenty of great libraries you can use to simplify the process. We highly recommend using them over trying to implement the protocol on your own.

Once you have your client_id and client_secret, use these URLs to authenticate:

  • To request authorization: https://my.kounta.com/authorize (don’t forget your redirect_uri)
  • To get access tokens: https://api.kounta.com/v1/token

We support the access_token authentication method for production, as well as the client_credentials method for development and testing. For authorization, both code and token (implicit) response types are supported.

If you prefer to use your own implementation rather than an OAuth 2.0 library, the spec has everything you'll need to know.

Content Type

Both JSON and XML data types are supported.

When sending data via POST or PUT, specify the format of the data you’re sending in the Content-Type header of your request. Acceptable values are text/xml, application/xml and application/json. Any other value will result in a 400 Bad Request response status.

The format of the response body is determined by the file extension of the requested endpoint, which can be either .json or .xml. Alternatively, you can omit the file extension if you include one of the aforementioned formats in your Accept header. If you omit the Accept header and the file extension, you’ll get a 406 Not Acceptable response status.

Data Types

Data in Kounta is represented in these formats:

  • Strings, encoded as UTF-8.
  • Numbers, denoted in XML by a type="number" attribute.
  • Booleans, denoted in XML by a type="boolean" attribute and a value of true or false.
  • Dates, denoted in XML by a type="date" attribute and represented as an ISO 8601 string.
  • Nulls, denoted in XML by null elements (e.g. <image/>).

type attributes will be included in XML responses for numbers, booleans and dates. They are not required in request bodies.

JSON natively understands data types, except for dates, which must be parsed manually.

Understanding data types isn’t critical, but it can help you avoid problems like inadvertently trimming leading zeroes off phone numbers and rendering null as a string.

Response Patterns

CRUD operations follow a few standard patterns. Deviations from these patterns are noted in the documents for individual actions.

  • Successful GET requests result in 200 OK response statuses.
  • Successful POST requests result in 201 Created response statuses, and Location headers containing the GET URIs of the newly created resources.
  • Successful PUT requests result in 200 OK response statuses, and include the updated record in the form of the corresponding GET action.
  • Successful DELETE requests result in 204 No Content response statuses.

Additionally:

  • Lists of records (e.g. GET /v1/customers ) often include abridged versions of records, containing only descriptive information (e.g. name, email) and an id. In these cases, you can GET the individual records by id for more detailed records.

Pagination

When you request a list of records (e.g. GET /v1/companies/5678/customers to list all customers), you’ll receive a maximum of 25 results. To retrieve the entire result set, you’ll need to request additional pages.

  • Look for the X-Pages response header. It’ll contain the number of pages available.
  • Request additional pages by including an X-Page header with your request.
  • Page numbers are zero-based. For example, if you receive X-Pages: 5, send X-Page: 1 for the second page, and X-Page: 4 for the last page.

Caching

Responses to GET requests will include Etag headers. Subsequent requests to the same endpoints should include this header’s value in an If-None-Match header. If we send you a 304 Not Modified response, you can save bandwidth and lighten our server load by using your cached copy.

Read more about Etag headers and HTTP caching here.

Errors

Kounta will use standard HTTP status codes when your requests cannot be satisfied.

Additional error information will be sent in the response body as key-value pairs, including an error code error, an error description error_description, and other diagnostically useful information.

Error responses are OAuth 2.0 compliant.

PUT vs PATCH

For simplicity, PATCH and PUT requests are identically treated as partial updates, i.e. only fields included in the request are altered. This documentation will always specify PUT, but you can use PATCH and PUT interchangeably if you like.

Testing

There are plenty of good plugins for both Firefox and Chrome for testing REST APIs.

If you prefer to use cURL or something a little less sophisticated, try sending an X-Pretty-Print: 1 header with your requests. We'll format the output with nice indentation to make it easier to read.