The Kamma RESTful API – v1

• Getting Started
• API v1
  • API Endpoints
  • Authentication
  • Content-Type Headers
  • OpenAPI Support
  • Detailed API Documentation
• Integration Guidelines
  • Basic Concepts
  • Mandatory and Optional Request Properties
  • The Property ID
  • Adding and Updating a Property
  • Querying a Property’s Licensing Compliance
  • Removing a Property

Getting Started

The Kamma API provides programmatic access, via a RESTful API, to the Kamma platform and allows you to integrate our platform into your business workflows.

You need a valid Kamma API key to access our API; you can request your API key from the Kamma team.

API v1

This page describes v1 of the Kamma API; this is the latest version.

API Endpoints

All API resources are accessed from the https://api.kammadata.com/v1 endpoint, which supports SSL access only. Accessing any API resource via vanilla HTTP will result in a Connection refused error (errno 61).

Authentication

All call to the Kamma API must be authenticated by a valid API key; this can be specified either as a URL query string parameter for GET requests or in the request body for POST requests. Whilst we will continue to support GET requests for v1 of the API, we strongly recommend protecting the integrity of your API key by using POST requests.

If an invalid API key is passed or if the API key is missing, an HTTP status of 400 Bad Request will be returned in the response headers.

Content-Type Headers

Unless explicitly documented in the detailed API documentation, all API request and response bodies must be encoded as UTF-8 JSON. API requests should set the Content-Type header as follows:

Content-Type: application/json

OpenAPI Support

All our API documentation is generated from our OpenAPI v3.0 Specification. Please see the OpenAPI Initiative website for more information.

You can also download the full Kamma OpenAPI specification for our API.

Detailed API Documentation

You can read the full documentation for the API on the Kamma RESTful API v1 page.

Integration Guidelines

Basic Concepts

The Kamma platform and RESTful API work on the concept of a property, which is uniquely identified and which has metadata which describes the property and which is used to check, determine and monitor the licensing compliance of a property.

Whilst we understand that most property management platforms for the rental market use a workflow which distinguishes between a lease, a tenancy and a property, the Kamma platform only models a property and uses the metadata associated with that property to check the licensing compliance. This is because Property Licensing legislation and compliance is attached to a property (and to a licensee), rather than to a lease.

Once a property has been created in the Kamma platform it is entirely expected that the metadata which describes the property can and will change over time and over multiple tenancies, but as described below, the identifier for a property should not change.

Mandatory and Optional Request Properties

All API methods that require a request body, expect a JSON object comprised of the documented name/value pairs, which are commonly termed JSON properties (not to be confused with the real world, bricks and mortar properties that the API relates to).

Each name/value property is either mandatory or optional.

Mandatory Properties

Any JSON property which is mandatory must be supplied in every request body. If a null value is permitted for a JSON property, supplying such a value will remove any previously stored value.

Optional Properties

Specifying an optional JSON property with a non null value and that has a value which is valid according to the API documentation:

• if not previously specified, this will create the property with the supplied value
• if previously specified, this will updated the current saved value with the supplied value

Specifying an optional JSON property with a null value, providing this is supported for this property according to the API documentation, will remove this property and any value previously stored.

Alternatively, omitting an optional JSON property from the request body will also remove this property and any value previously stored.

The Property ID

Each property that is registered in the Kamma platform is identified by a unique identifier, the PropertyId that is required when the property is initially created in the platform or when an existing property is updated or removed from the platform.

It’s important to know that unique refers to the backend platform or workflow that your business uses. Property identifiers are sandboxed to your Kamma account, not to the platform as a whole.

We recommend that you use an identifier that is provided by the property management platform that your business is using, such as a database table primary key or a UUID or GUID. As mentioned above, the basic unit of the Kamma platform is the property. The platform does not model or take into account other concepts that may be associated with a property in your system, such as a lease or a tenancy. It’s critically important that the PropertyId you use is persistent across all stages of a rental process; if a PropertyId changes, it will be considered to be a different property by the GetRentr platform.

Adding and Updating a Property

A property is added to the Kamma platform or an existing property’s metadata is updated with the /property/process (Register/Update Property) API method. This method has both mandatory metadata parameters and determining metadata parameters as described below.

Determining metadata parameters are those which are needed in order to fully and correctly determine the licensing compliance of a property. It is fully expected that the determining metadata associated with a property will change over time, due to changes in leases or tenancies. The need for some items of this additional metadata is dependent on the property’s location, but provision of all of these fields ensures Kamma’s ability to accurately determine the Property Licensing requirements of all properties.

Mandatory metadata parameters are those which are the minimum needed to register a property within the Kamma platform. It’s important to note that using only the mandatory parameters will not enable the Kamma platform to determine or monitor the licensing compliance of the property.

Thus, the mandatory metadata parameters can be thought of as a placeholder to register the property at an early stage in your business’s workflow and that the metadata for the property will be updated with the full set of determining metadata parameters during the course of your workflow. Once the full set of determining metadata parameters are updated for a given property, the Kamma platform will be able to report on the licensing compliance for that property and then monitor for compliance changes, based on both external factors, such as licensing scheme durations as well as internal factors, such as amending and updating the property metadata.

The mandatory metadata parameters for a property are:

1. Property ID
2. Address
3. Postcode

The determining metadata parameters for a property are:

1. The number of people resident in the property
2. The number of households living in the property
3. The number of storeys in the building that the property is part of
4. The number of bedrooms in the property or the number of flats in a converted building
5. Whether the property is above a commercial premises
6. The property category
7. The property type

Querying a Property’s Licensing Compliance

The current licensing compliance for a property, based on the metadata that has been supplied when the property was initially created in the platform or last updated is provided by the /property/view/{propertyId} (View Property) API method.

Removing a Property

If a property is no longer required to be registered or monitored by the Kamma platform, it can be removed by the /property/disable (Disable Property) API method.