The Kamma RESTful API

Topics

• 1 Getting Started
• 2 API v1
  • 2.1 API Endpoints
  • 2.2 Authentication
  • 2.3 Content-Type Headers
  • 2.4 OpenAPI Support
  • 2.5 Detailed API Documentation
• 3 Integration Guidelines
  • 3.1 Basic Concepts
  • 3.2 Required and Optional JSON Request Properties
    • 3.2.1 Required JSON Properties
    • 3.2.2 Optional JSON Properties
  • 3.3 The Property ID
• 4 Getting Help and Support
• 5 API Workflows
  • 5.1 Obtaining an Authorisation Token
    • 5.1.1 Example Request and Response
  • 5.2 Creating and Updating a Property
    • 5.2.1 Mandatory JSON Request Properties
    • 5.2.2 Determining JSON Request Properties
    • 5.2.3 Override JSON Request Properties
    • 5.2.4 Example Request and Response
  • 5.3 Querying a Property's Current Licensing Compliance
    • 5.3.1 Example Request and Response
  • 5.4 Deleting a Property
    • 5.4.1 Example Request and Response

1 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'll need both a valid Kamma API key and a valid Kamma manager reference to access our API; you can request these from the Kamma team when you're setting up access to the API.

2 API v1

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

2.1 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 return an HTTP redirect status of 302 Found in the response headers, together with a Location response header with the corresponding SSL protected URL for the resource.

										
$ http post http://api.kammadata.com/v1/property/view/[property-id]

 HTTP/1.1 302 Found
 Cache-Control: max-age=1
 Connection: keep-alive
 Content-Length: 271
 Content-Type: text/html; charset=iso-8859-1
 Location: https://api.kammadata.com/v1/property/view/[property-id]
										
									

2.2 Authentication

All calls to the Kamma API must be either authenticated by a valid API key or by an authentication token generated by the API for an 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.

For more information on generating an authentication token from an API key, see the section Obtaining an Authorisation Token below.

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

2.3 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
										
									

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

2.5 Detailed API Documentation

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

3 API Integration Guidelines

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

3.2 Required and Optional JSON 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 required or optional.

3.2.1 Required JSON Properties

Any JSON property which is required 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.

3.2.2 Optional JSON Properties

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

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

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

4 Getting Help and Support

We have designed the Kamma API to be simple yet intuitive and powerful. But there may be a time when something isn't quite working as you expect it to.

To speed things up, it will help us massively if you can provide the following information for us in an email to the Kamma team and we'll do our very best to help you.

1. The API key that you are using; our API keys are unique to each of our production environments
2. The full URL of the API method
3. The full set of HTTP request headers
4. The full request body
5. The HTTP response code received from the API
6. The full set of HTTP response headers
7. The full response body

All of this information will allow us to replicate the API method and to provide help and support as quickly as we can.

5 API Workflows

5.1 Obtaining an Authorisation Token

An authorisation token is generated and returned for a combination of API key and manager reference by the /auth/manager method.

Regardless of the exact sequence of API methods that you wish to use, all sequences of API transactions should follow the same basic workflow of obtaining an authorisation token and using this token to authenticate with all other subsequent API methods.

An authoritisation token has a finite lifetime; once this expires an authentication error will be returned, such as shown below and a new token should be obtained in order to continue to use the API's method. The return body from each API method should be checked to ensure that the token is still valid.

										
{
    "api_id": [api-id],
    "error": true,
    "error_type": "authentication",
    "error_message": "showLogin"
}
										
									

5.1.1 Example Request and Response

This section provides example requests and responses for invoking the /auth/manager method using the curl, http and wget command line tools.

Remember to replace [manager-ref] and [api-key] with your own manager reference and API key and also use the value of [auth-token] in subsequent API methods.

$ curl --location --request POST 'https://api.kammadata.com/v1/auth/manager/[manager-ref]' --header 'Content-Type: application/json' --verbose --data-raw '{
    "secret": "[api-key]"
}'

> POST /v1/auth/manager/[manager-ref] HTTP/1.1
> Host: api.kammadata.com
> User-Agent: curl/7.70.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 52
< HTTP/1.1 200 OK
< Date: Thu, 18 Jun 2020 09:58:23 GMT
< Content-Type: application/json
< Content-Length: 92
< Connection: keep-alive
< Cache-Control: no-store, no-cache, must-revalidate
< Pragma: no-cache
< Access-Control-Allow-Headers: origin, accept, content-type
< Access-Control-Allow-Methods: GET, POST, OPTIONS
{
    "api_id": 7258,
    "success": true,
    "token": "[auth-token]"
}
									

$ http POST https://api.kammadata.com/v1/auth/manager/[manager-ref] secret=[api-key] --verbose

POST /v1/auth/manager/[manager-ref] HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 52
Content-Type: application/json
Host: api.kammadata.com
User-Agent: HTTPie/2.1.0

{
    "secret": "[api-key]"
}

HTTP/1.1 200 OK
Access-Control-Allow-Headers: origin, accept, content-type
Access-Control-Allow-Methods: GET, POST, OPTIONS
Cache-Control: no-store, no-cache, must-revalidate
Connection: keep-alive
Content-Length: 92
Content-Type: application/json
Date: Thu, 18 Jun 2020 15:34:45 GMT
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Pragma: no-cache

{
    "api_id": [api-id],
    "success": true,
    "token": "[auth-token]"
}
														

$ wget https://api.kammadata.com/v1/auth/manager/[manager-ref] --quiet --method POST --header 'Content-Type: application/json' --body-data '{
    "secret": "[api-key]"
}' --output-document -

POST /v1/auth/manager/[manager-ref] HTTP/1.1
{
    "api_id": [api-id],
    "success": true,
    "token": "[auth-token]"
}
														

5.2 Creating and Updating a Property

A new property can be added to the Kamma platform or the metadata associated with an existing property can be updated with the /property/process method.

The request body for this method contains three classes of JSON property; mandatory properties, determining properties and override properties, which are described below.

5.2.1 Mandatory JSON Request Properties

Mandatory request properties are the minimum properties which are required in order to create a property within the Kamma platform. It's important to note that using only the mandatory request properties will not supply sufficient information to allow the Kamma platform to determine or to monitor the licensing compliance of the property.

Thus the mandatory request properties can be thought of as a placeholder to enter a property into the Kamma platform at an early stage of your business's workflow and that it is expected that the determining properties and optionally, the override properties, will be updated during the end to end course of your workflow.

The mandatory request properties are:

1. The Property Id (property in the request body)
2. The property's address (address_1 in the request body; address_2 through address_5 are optional)
3. The property's full postcode (postcode in the request body)

5.2.2 Determining JSON Request Properties

Determining request properties 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 properties will change over time, due to changes in leases or tenancies. The precise requirements for determining properties are dependent on the physical location of the property and of the licensing scheme or schemes which are in place at any given time. As a result, providing all of these properties during the course of your workflow ensures that the Kamma platform is able to accurately determine the Property Licensing requirements of all properties.

The determining request properties are:

1. The number of people resident in the property (people in the request body)
2. The number of households resident in the property (households in the request body)
3. The number of external storeys in the building that the property is part of (storeys in the request body)
4. The number of internal storeys that comprise the property (storeys_internal in the request body)
5. Whether the property is above a commercial premises (above_commercial in the request body)
6. The property class (property_class in the request body)
7. The property category (category in the request body)

5.2.3 Override JSON Request Properties

If the category determining JSON request property is provided as a non null value then this may have an overriding effect on a licence determination.

For example:

• Specifying the property category as licenseable will mark the property as requiring a mandatory licence.
• Specifying the category as s254 or s257 will apply an appropriate additional licence if the property falls within such a scheme.
• Specifying the category as single will discount additional schemes where appropriate.

5.2.4 Example Request and Response

This section provides example requests and responses for invoking the /property/process method using the curl, http and wget command line tools.

Remember to replace [property-ref] and [auth-token] with your own property reference and also use the value of [auth-token] obtained from the /auth/manager method.

$ curl --location --request POST 'https://api.kammadata.com/v1/property/process' --header 'Content-Type: application/json' --verbose --data-raw '{
	"secret": "[api-key]",
	"property": "[property-ref]",
	"address_1": "52 Crown Street",
	"address_2": "London",
	"address_3": "",
	"address_4": "",
	"address_5": "",
	"postcode": "WC1E 6JP",
	"people": 5,
	"households": 5,
	"storeys": 1,
	"storeys_internal": 1,
	"above_commercial": 1,
	"rooms": 3,
	"category": "licenseable",
	"property_class": "flat"
}'

> POST /v1/property/process HTTP/1.1
> Host: api.kammadata.com
> User-Agent: curl/7.70.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 389
< HTTP/1.1 200 OK
< Date: Fri, 19 Jun 2020 14:45:40 GMT
< Content-Type: application/json
< Content-Length: 753
< Connection: keep-alive
< Cache-Control: no-store, no-cache, must-revalidate
< Pragma: no-cache
< Access-Control-Allow-Headers: origin, accept, content-type
< Access-Control-Allow-Methods: GET, POST, OPTIONS
<
{
    "api_id": 7329,
    "success": true,
    "reference": "[property-ref]",
    "licence_state": "checked",
    "licence_type": "mandatory",
    "licence_advice": "Mandatory licence required",
    "council": "Camden",
    "council_websites": [
        "https:\/\/www.camden.gov.uk\/houses-multiple-occupation"
    ],
    "licence_application": null,
    "planning_application": null,
    "licences_at_postcode": true,
    "licence_at_address": "yes",
    "licences_at_address": {
        "type": "additional",
        "address": "52 Crown Street, Camden, London, WC1E 6JP",
        "licencee": "Mr R E Kamma",
        "people": 3,
        "households": 3,
        "status": "complete",
        "date_start": 1582934400,
        "date_end": 1740700800
    }
}									

$ http POST https://api.kammadata.com/v1/property/process token=[api-key] property="[property-ref]" address_1="52 Crown Street" address_2="London" address_3="" address_4="" address_5="" postcode="WC1E 6JP" people=5 households=5 storeys=1 storeys_internal=1 above_commercial=1 rooms=3 category="licenseable" property_class="flat" --verbose

POST /v1/property/process HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 389
Content-Type: application/json
Host: api.kammadata.com
User-Agent: HTTPie/2.1.0

{
    "above_commercial": 1,
    "address_1": "52 Crown Street",
    "address_2": "London",
    "address_3": "",
    "address_4": "",
    "address_5": "",
    "category": "licenseable",
    "households": 5,
    "people": 5,
    "postcode": "WC1E 6JP",
    "property": "[property-ref]",
    "property_class": "flat",
    "rooms": 3,
    "storeys": 1,
    "storeys_internal": 1,
    "token": "[auth-token]"
}

HTTP/1.1 200 OK
Access-Control-Allow-Headers: origin, accept, content-type
Access-Control-Allow-Methods: GET, POST, OPTIONS
Cache-Control: no-store, no-cache, must-revalidate
Connection: keep-alive
Content-Length: 753
Content-Type: application/json
Date: Fri, 19 Jun 2020 14:48:43 GMT
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Pragma: no-cache

{
    "api_id": 7330,
    "council": "Camden",
    "council_websites": [
        "https://www.camden.gov.uk/houses-multiple-occupation"
    ],
    "licence_advice": "Mandatory licence required",
    "licence_application": null,
    "licence_at_address": "yes",
    "licence_state": "checked",
    "licence_type": "mandatory",
    "licences_at_address": {
        "address": "52 Crown Street, Camden, London, WC1E 6JP",
        "date_end": 1740700800,
        "date_start": 1582934400,
        "households": 3,
        "licencee": "Mr R E Kamma",
        "people": 3,
        "status": "complete",
        "type": "additional"
    },
    "licences_at_postcode": true,
    "planning_application": null,
    "reference": "[property-ref]",
    "success": true
}
														

$ wget https://api.kammadata.com/v1/property/process --quiet --method POST --header 'Content-Type: application/json' --body-data '{
    "token": "[auth-token]",
    "property": "[property-ref]",
    "address_1": "52 Crown Street",
    "address_2": "London",
    "address_3": "",
    "address_4": "",
    "address_5": "",
    "postcode": "WC1E 6JP",
    "people": 5,
    "households": 5,
    "storeys": 1,
    "storeys_internal": 1,
    "above_commercial": 1,
    "rooms": 3,
    "category": "licenseable",
    "property_class": "flat"
}' --output-document -

POST /v1/property/view/[property-ref] HTTP/1.1
{
    "api_id": 7331,
    "success": true,
    "reference": "[property-ref]",
    "licence_state": "checked",
    "licence_type": "mandatory",
    "licence_advice": "Mandatory licence required",
    "council": "Camden",
    "council_websites": [
        "https:\/\/www.camden.gov.uk\/houses-multiple-occupation"
    ],
    "licence_application": null,
    "planning_application": null,
    "licences_at_postcode": true,
    "licence_at_address": "yes",
    "licences_at_address": {
        "type": "additional",
        "address": "52 Crown Street, Camden, London, WC1E 6JP",
        "licencee": "Mr R E Kamma",
        "people": 3,
        "households": 3,
        "status": "complete",
        "date_start": 1582934400,
        "date_end": 1740700800
    }
}														

5.3 Querying a Property's Current Licensing Compliance

The current licensing compliance for a property, based on the Property Id and the current information that is stored in the Kamma platform can be queried with the /property/view method .

5.3.1 Example Request and Response

This section provides example requests and responses for invoking the /property/view method using the curl, http and wget command line tools.

Remember to replace [property-ref] and [auth-token] with your own property reference and also use the value of [auth-token] obtained from the /auth/manager method.

$ curl --location --request POST 'https://api.kammadata.com/v1/property/view/[property-ref]' --header 'Content-Type: application/json' --verbose --data-raw '{
    "secret": "[api-key]"
}'

> POST /v1/property/view/[property-ref] HTTP/1.1
> Host: api.kammadata.com
> User-Agent: curl/7.70.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 51
< HTTP/1.1 200 OK
< Date: Thu, 18 Jun 2020 15:19:09 GMT
< Content-Type: application/json
< Content-Length: 753
< Connection: keep-alive
< Cache-Control: no-store, no-cache, must-revalidate
< Pragma: no-cache
< Access-Control-Allow-Headers: origin, accept, content-type
< Access-Control-Allow-Methods: GET, POST, OPTIONS
<
{
    "api_id": 7287,
    "success": true,
    "reference": "[property-ref]",
    "licence_state": "checked",
    "licence_type": "mandatory",
    "licence_advice": "Mandatory licence required",
    "council": "Camden",
    "council_websites": [
        "https:\/\/www.camden.gov.uk\/houses-multiple-occupation"
    ],
    "licence_application": null,
    "planning_application": null,
    "licences_at_postcode": true,
    "licence_at_address": "yes",
    "licences_at_address": {
        "type": "additional",
        "address": "52 Crown Street, Camden, London, WC1E 6JP",
        "licencee": "Mr R E Kamma",
        "people": 3,
        "households": 3,
        "status": "complete",
        "date_start": 1582934400,
        "date_end": 1740700800
    }
}									

$ http POST https://api.kammadata.com/v1/property/view/[property-ref] secret=[api-key] --verbose

POST /v1/property/view/[property-ref] HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 51
Content-Type: application/json
Host: api.kammadata.com
User-Agent: HTTPie/2.1.0

{
    "token": "[auth-token]"
}

HTTP/1.1 200 OK
Access-Control-Allow-Headers: origin, accept, content-type
Access-Control-Allow-Methods: GET, POST, OPTIONS
Cache-Control: no-store, no-cache, must-revalidate
Connection: keep-alive
Content-Length: 753
Content-Type: application/json
Date: Thu, 18 Jun 2020 15:31:01 GMT
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Pragma: no-cache

{
    "api_id": 7290,
    "council": "Camden",
    "council_websites": [
        "https://www.camden.gov.uk/houses-multiple-occupation"
    ],
    "licence_advice": "Mandatory licence required",
    "licence_application": null,
    "licence_at_address": "yes",
    "licence_state": "checked",
    "licence_type": "mandatory",
    "licences_at_address": {
        "address": "52 Crown Street, Camden, London, WC1E 6JP",
        "date_end": 1740700800,
        "date_start": 1582934400,
        "households": 3,
        "licencee": "Mr R E Kamma",
        "people": 3,
        "status": "complete",
        "type": "additional"
    },
    "licences_at_postcode": true,
    "planning_application": null,
    "reference": "[property-ref]",
    "success": true
}
														

$ wget https://api.kammadata.com/v1/property/view/[property-ref] --quiet --method POST --header 'Content-Type: application/json' --body-data '{
    "token": "[auth-token]"
}' --output-document -

POST /v1/property/view/[property-ref] HTTP/1.1
{
    "api_id": 7294,
    "success": true,
    "reference": "[property-ref]",
    "licence_state": "checked",
    "licence_type": "mandatory",
    "licence_advice": "Mandatory licence required",
    "council": "Camden",
    "council_websites": [
        "https:\/\/www.camden.gov.uk\/houses-multiple-occupation"
    ],
    "licence_application": null,
    "planning_application": null,
    "licences_at_postcode": true,
    "licence_at_address": "yes",
    "licences_at_address": {
        "type": "additional",
        "address": "52 Crown Street, Camden, London, WC1E 6JP",
        "licencee": "Mr R E Kamma",
        "people": 3,
        "households": 3,
        "status": "complete",
        "date_start": 1582934400,
        "date_end": 1740700800
    }
}														

5.4 Deleting a Property

If a property is no longer required to be held within the Kamma platform or monitored for changes to licensing compliance, it can be removed by the /property/disable method. This process is sometimes termed archival or deletion in some business workflows.

5.4.1 Example Request and Response

This section provides example requests and responses for invoking the /property/disable method using the curl, http and wget command line tools.

Remember to replace [property-ref] and [auth-token] with your own property reference and also use the value of [auth-token] obtained from the /auth/manager method.

$ curl --location --request POST 'https://api.kammadata.com/v1/property/disable' --header 'Content-Type: application/json' --verbose --data-raw '{
    "token": "[api-key]",
    "property": "[property-ref]"
}'

> POST /v1/property/disable HTTP/1.1
> Host: api.kammadata.com
> User-Agent: curl/7.70.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 78
< HTTP/1.1 200 OK
< Date: Fri, 19 Jun 2020 14:21:56 GMT
< Content-Type: application/json
< Content-Length: 43
< Connection: keep-alive
< Cache-Control: no-store, no-cache, must-revalidate
< Pragma: no-cache
< Access-Control-Allow-Headers: origin, accept, content-type
< Access-Control-Allow-Methods: GET, POST, OPTIONS
<
{
    "api_id": 7320,
    "success": true
}									

$ http POST https://api.kammadata.com/v1/property/disable token=[api-key] property=[property-ref] --verbose

POST /v1/property/disable HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 68
Content-Type: application/json
Host: api.kammadata.com
User-Agent: HTTPie/2.1.0

{
    "property": "[property-ref]",
    "token": "[auth-token]"
}

HTTP/1.1 200 OK
Access-Control-Allow-Headers: origin, accept, content-type
Access-Control-Allow-Methods: GET, POST, OPTIONS
Cache-Control: no-store, no-cache, must-revalidate
Connection: keep-alive
Content-Length: 43
Content-Type: application/json
Date: Fri, 19 Jun 2020 14:27:57 GMT
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Pragma: no-cache

{
    "api_id": 7322,
    "success": true
}														

$ wget https://api.kammadata.com/v1/property/disable --quiet --method POST --header 'Content-Type: application/json' --body-data '{
    "token": "[auth-token]",
    "property": "[property-ref]"
}' --output-document -

POST /v1/auth/manager/[manager-ref] HTTP/1.1
{
    "api_id": 7234,
    "success": true
}