The Kamma RESTful API v2

Published 28th November 2023

Introduction

The Kamma API is a RESTful HTTP JSON API that offers self-descriptive URLs, speaks JSON for both request and response bodies and uses standard HTTP response codes and verbs.

Core Concepts

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 in client-side or front-end code that can be viewed in a browser.

HTTPS Only Access

All API requests should be made over an encrypted network connection using HTTPS. Calls made over plain or vanilla HTTP will return an HTTP 308 (permanent redirect) status code and will contain the HTTPS equivalent URL that should be followed in the response’s Location header.

Rate Limiting

To preserve the stability and availability of the Kamma platform, the Kamma API has rate limits that cap the number of requests that you can make against all endpoints of the API.

Please see the Rate Limiting section of the API documentation at https://kamma.api.kammadata.com/docs/#rate-limiting for more information.

API 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

The full set of HTTP response codes also allow for 1xx codes; these are informational codes that are not currently used by the Kamma API.

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 the response body 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"
}

API 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.

The legacy Version 1 API is still provided for customers who have not yet migrated to API Version 2. Please see the end of this page for more information.

Property Identifiers

The Kamma API needs to be able to identify a specific property in a unique and unambiguous manner to give you the best possible results. The API uses one of three identifiers to refer to a property, summarised below in order of preferred use:

UPRNs – an Ordnance Survey/Geoplace Unique Property Reference Number, such as geoplace:uprn:100011623123
Kamma Property Id – a unique identifier returned from the Kamma Id, such as kamma:property:ea357bde17331f4217bd7898c50175fa
Address – a full street level address, including the postcode, URL encoded according to RFC:3989, such as kamma:address:thanet+house+231+strand+london+WC2R+1DA

Please see the Property Identifiers section of the API documentation at https://kamma.api.kammadata.com/docs/#property-identifiers for more details.

Suggested API Workflows

Full and detailed API documentation is available at https://kamma.api.kammadata.com/docs/ but in the sections below you’ll find a set of suggested workflows for integrating your application with the Kamma API quickly and easily.

Checking the Licensing Legislation for a Property

The current HMO licensing schemes and consultations that may apply to a property can be checked by the following API endpoint:


GET /api/properties/determination-check/{property-identifier}

Where property-identifier can be a UPRN, a Kamma Property Id or an address.

It’s important to note that this endpoint cannot be used to determine whether a property is currently compliant with legislation, only that the property may be impacted by a scheme or consultation. Modelling the licensing requirements for a single property or for a portfolio of properties is described below.

See the Legislation Checker section of the API documentation at https://kamma.api.kammadata.com/docs/#legislation-checker-methods for more details.

Checking the Licensed Status of a Property

Whether a property is currently an HMO or has been in the past, together with details on current and historic licences for a property can be determined by the following API endpoint:


GET /api/properties/licensing-check/{property-identifier}

Where property-identifier can be a UPRN, a Kamma Property Id or an address.

Full details on each of these endpoints can be found at https://kamma.api.kammadata.com/docs/#property-methods.

Creating and Maintaining Licensing Requirements for a Property Portfolio

A property portfolio and associated tenancy modelling for licensing compliance can be managed by the following API endpoints. This allows you to model functionality that is equivalent to Kamma Manager.

Full details on each of the following endpoints can be found at https://kamma.api.kammadata.com/docs/#property-methods.

Creating a New Property


POST /api/properties/create

This endpoint creates a new property in the Kamma Platform and returns licensing compliance determination that is able to be calculated based on the tenancy information supplied. If all information is provided on creation an accurate determination can be made, otherwise this endpoint can be used to create a placeholder property and the tenancy information can be refined at a later stage by the Property Sync endpoint.

Modifying an Existing Property


PUT /api/properties/sync/{property-identifier}

Where property-identifier must be a Kamma Property Id.

This endpoint updates an existing property in the Kamma platform and returns licensing compliance determination that is able to be calculated based on the tenancy information supplied.

Checking the Current Compliance for an Existing Property


GET /api/properties/property-check/{property-identifier}

Where property-identifier must be a Kamma Property Id.

This endpoint returns the current licensing compliance determination for the property and tenancy information that is currently held in the Kamma Platform.

Deleting an Existing Property


DELETE /api/properties/archive/{property-identifier}

Where property-identifier must be a Kamma Property Id.Properties held in the Kamma Platform will be continually monitored for compliance. To remove a property from the Platform and to cease monitoring the property, it should be archived.

Checking the Energy Performance Certificate of a Property

The current Energy Performance Certificate for a property can be checked by the following API endpoint:


GET /api/properties/epc-check/{property-identifier}

Where property-identifier can be a UPRN, a Kamma Property Id or an address.

Please see https://kamma.api.kammadata.com/docs/#epc-checker-methods for full documentation of this endpoint.

Legacy API Version 1 Support

The legacy Version 1 of the Kamma API is now 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.

Customers who have not yet migrated to Version 2 of the Kamma API can find the introduction to the legacy Version 1 API at https://www.kammadata.com/support/api/v1/ and more detailed API documentation at https://www.kammadata.com/support/api/api-v1/.

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.

Book a demo or get in touch

If you’d like to see the power of the Kamma platform in action, you can book a demo with us by simply clicking on the Book a Demo link at the top of the page.

Otherwise, email us at hello@kammadata.com or let us know your contact details using this form and we will get back to you as soon as we can.