Published 12th August 2019
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.
This page describes v1 of the Kamma API; this is the latest version.
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]
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.
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
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.
You can read the full documentation for the API on the Kamma RESTful API v1 page.
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.
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.
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.
Specifying an optional JSON property with a non null
value and which has a value that is valid according to the API documentation will:
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.
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.
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.
All of this information will allow us to replicate the API method and to provide help and support as quickly as we can.
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"
}
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]"
}
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.
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:
property
in the request body)address_1
in the request body; address_2
through address_5
are optional)postcode
in the request body)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:
people
in the request body)households
in the request body)storeys
in the request body)storeys_internal
in the request body)above_commercial
in the request body)property_class
in the request body)category
in the request body)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:
licenseable
will mark the property as requiring a mandatory licence.s254
or s257
will apply an appropriate additional licence if the property falls within such a scheme.single
will discount additional schemes where appropriate.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
}
}
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 .
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
}
}
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.
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
}
Want to 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, you can get in touch with us using the form below and we will get back to you as soon as we can.
Sending message...
Sorry, but something went wrong. Please let us know and we'll do our best to fix it.
Hi
Thanks for sending us your message. You'll be hearing from us shortly.
How to find us
As a result of the current and ongoing COVID-19 pandemic, Kamma is a fully remote company; but you can always connect and get in touch with us, by phone, by email or via our Contact Us form.
Kamma Limited, 7 Bell Yard, London, WC2A 2JR, United Kingdom
+44 (0) 203 872 2940