Integrate your product with Kounta
Kounta uses an OAuth 2.0 compliant RESTful API for easy integration with third-party applications.
Kounta’s REST API is based at
https://api.kounta.com/v1/. There is no unencrypted (non-SSL) version available.
Two types of authentication are available:
- For development, you can use Basic Access Authorization.
- For production, you’ll need to use OAuth 2.0.
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
Authorization: Basic eHh4Onl5eQ==
Read this article for a detailed description of Basic Access Authorization.
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_secret, use these URLs
- To request authorization:
https://my.kounta.com/authorize(don’t forget your
- To get access tokens:
We support the
access_token authentication method for production, as well as
client_credentials method for development and testing. For
token (implicit) response types
If you prefer to use your own implementation rather than an OAuth 2.0 library, the spec has everything you'll need to know.
Both JSON and XML data types are supported.
When sending data via
PUT, specify the format of the
data you’re sending in the
Content-Type header of your request. Acceptable
application/json. Any other value will result in a
Request response status.
The format of the response body is determined by the file extension of the requested
endpoint, which can be either
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 in Kounta is represented in these formats:
- Strings, encoded as UTF-8.
Numbers, denoted in XML by a
Booleans, denoted in XML by a
type="boolean"attribute and a value of
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.
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
as a string.
CRUD operations follow a few standard patterns. Deviations from these patterns are noted in the documents for individual actions.
GETrequests result in
200 OKresponse statuses.
POSTrequests result in
201 Createdresponse statuses, and
Locationheaders containing the
GETURIs of the newly created resources.
PUTrequests result in
200 OKresponse statuses, and include the updated record in the form of the corresponding
DELETErequests result in
204 No Contentresponse statuses.
Lists of records (e.g.
GET /v1/customers) often include abridged versions of records, containing only descriptive information (e.g.
id. In these cases, you can
GETthe individual records by
idfor more detailed records.
When you request a list of records (e.g.
/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-Pagesresponse header. It’ll contain the number of pages available.
- Request additional pages by including an
X-Pageheader with your request.
- Page numbers are zero-based. For example, if you receive
X-Pages: 5, send
X-Page: 1for the second page, and
X-Page: 4for the last page.
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
Read more about
Etag headers and HTTP caching here.
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
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
PUT interchangeably if you like.
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.