The Kamma RESTful API

Introduction

The Kamma API is an HTTP RESTful web API; it offers self-descriptive URLs, speaks JSON for both requests and responses and uses standard HTTP response codes and verbs.

Authentication

The Kamma API uses API keys to authenticate requests; our support team will enable your account for API access and share your API key with you.

Your API key enables access to the Kamma API and to your information which is held securely within the Kamma platform; be sure to keep your API key secure. Do not share your API key where it can be publicly accessed, such as GitHub or GitLab public repositories or client-side code that can be viewed in a browser.

Authentication to the Kamma API is performed by an HTTP header provided as part of each request; you provide your API key as the value for the X-SSO-API-Key header.

All API requests should be made over HTTPS. Calls made over plain or vanilla HTTP will return an HTTP 308 permanent redirect status with the HTTPS equivalent URL that should be followed as the Location header.

Errors

We use standard HTTP response codes to indicate the success or the failure of an API request.

• 2xx response codes are success codes
• 3xx response codes are redirection codes and usually show that an HTTP request was made and the request should be repeated as an HTTPS request
• 4xx response codes are errors with the request, meaning something was wrong with the request and the API could not act on it
• 5xx response codes are errors with the Kamma API’s servers and are extremely rare

HTTP response codes also allow for 1xx codes and are informational codes that the Kamma API does not use.

In addition to the HTTP response codes, the API also returns a set of properties that describe an error in more detail and may allow you to respond to and correct the error programmatically.

• status – the HTTP response code
• message – the human-readable description of the HTTP response code
• code – a Kamma API error code that qualifies the HTTP response code
• description – a human-readable description of the Kamma API error code
• response_id – a unique identifier assigned to the API request; this identifier can be used by the Kamma support team to help diagnose and resolve problems

This is an example of an error code returned as a result of the API receiving a bad request:

{
    "status": 400,
    "message": "Bad Request",
    "code": 101000,
    "description": "The identity token was invalid, must be in the form of geoplace:uprn:1234, kamma:address:123+Street or kamma:property:ea357bde17331f4217bd7898c50175fa. Please refer to docs for more information.",
    "response_id": "1234-1234-1234-1234-1234"
}

​Versioning

When a breaking or backwards-incompatible change is made to the Kamma API, a new version is released. This guide describes Version 2 of the Kamma API which is the latest version.

API Version 1 Support

Version 1 of the Kamma API is officially sunset; this means that we will continue to provide this version of the API but no new functionality or changes will be made, unless such changes are required to preserve the stability and security of the Kamma platform. No new API credentials will be offered to our customers for this version of the API.

We plan to deprecate and cease to provide access to Version 1 of the API at a future date and will continue to provide the service for a period of at least 9 months prior to the deprecation date.

The Version 1 API’s user guide and detailed supporting API documentation will continue to be made available until Version 1 is deprecated.

Property Identifiers

A property is identified in the API as a machine tag, sometimes called a triple tag. This takes the form namespace:predicate:value:

• The namespace is like a subject, topic or theme
• The predicate qualifies in more detail the namespace
• The value is … the value of the identifier

A Kamma property identifier can be one of the following three machine tag variants:

1. A Unique Property Reference Number or UPRN such as geoplace:uprn:100011623123
2. A Kamma API property identifier, returned from the API by the create property method, such as kamma:property:ea357bde17331f4217bd7898c50175fa
3. A full address including postcode, URL encoded according to RFC:3989, such as kamma:address:7+Bell+Yard+London+WC2A+2JR

Core Concepts

Detailed API documentation for Version 2 of the API is available as part of the API at https://kamma.api.kammadata.com/docs.

At a high level, the API provides methods that allow you to perform the following tasks

1. Get the current licensing status for a property; detailed in the Determination Checker Methods section of the API documentation.
2. Get the current and historic HMO status of for property; detailed in the Licensing Checker Methods section of the API documentation.
3. Get the current Energy Performance Certificate status for a property; detailed in the EPC Checker Methods section of the documentation.
4. Create, check and delete a property in the Kamma platform for modelling a specific set of tenancy data against any current licensing schemes; detailed in the Property Methods section of the API documentation.