Introduction

Base URL: https://kamma.api.kammadata.com

Getting Started

The Kamma API provides programmatic access, via a RESTful API, to Kamma’s technical architecture allowing you to integrate into your platform.

In order to gain access, you'll need a valid Kamma API key. If you do not have one, please request it at support@kammadata.com.

Endpoints

$ http GET https://kamma.api.kammadata.com/api/properties/determination-check/geoplace:uprn:123456789123

 HTTP/1.1 302 Found
 Cache-Control: max-age=1
 Connection: keep-alive
 Content-Length: 271
 Content-Type: text/html; charset=utf-8
 Location: https://kamma.api.kammadata.com/api/properties/determination-check/geoplace:uprn:123456789123

All API resources are accessed from the https://kamma.api.kammadata.com/api endpoint, which supports SSL/TLS 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.

This documentation aims to provide all the information you need to work with our API.

Headers

Content-Type: application/json
Accept: application/json

Unless explicitly documented in this 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:

a Content-Type header with the value application/json.
an Accept header with the value application/json.

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. If you exceed the rate limit an HTTP status code of 429 Too Many Requests will be returned.

The Kamma API provides HTTP response headers that should be examined by your application to determine the maximum and current rate limits for your API key.

X-RateLimit-Limit - the maximum number of requests that you can make within the current rate limiting period.

X-RateLimit-Remaining - the number of requests remaining within the current rate limiting period.

Your application should inspect the HTTP status code and response headers and take action accordingly. If rate limited, you should implement a phased back-off and retry schedule until the current rate limiting period has expired.

Concurrency Limits

Informal concurrency limits of 2 maximum concurrent requests are in place. While not strictly enforced, adhering to these guidelines ensures optimal performance.

Property Identifiers

The Kamma API allows you to query a single property and to manage a portfolio of multiple properties. To operate efficiently, and accurately it's critical to identify a single, specific and unique property. This can in one of three ways:

Kamma Property Id

kamma:property:ea357bde17331f4217bd7898c50175fa

The Kamma Property Id is a unique identifier returned in an API response body by the Property Create endpoint, which is part of the Property Methods collection of endpoints. This identifier is then used in the URI path to uniquely identify a property in other endpoints within the Property Methods collection.

A Property Id is a string value, prefixed with the kamma:property: namespace and predicate.

Please remember that a Property Id refers to a specific property that has already been added to the Kamma Platform by the API; you cannot supply your own version of a Property Id, but should you with to associate an identifier of your own with a property, the external_reference field in the request body for the Property Create and Property Sync endpoints enable this.

UPRN

geoplace:uprn:100023433011

A unique identifier for an addressable location, including a specific property, that is found in data sets produced by Ordnance Survey, in services that use this data and in some open data sets.

In the context of the Kamma API a UPRN uniquely and unambiguously identifies a specific property. If you have access to UPRNs for your properties you should use this identifier for your properties in the Kamma API in preference to an address (see below).

A UPRN is an integer value, prefixed with the geoplace:uprn: namespace and predicate.

Address

kamma:address:thanet+house+231+strand+london+wc2r+1da

A full street level address, including the postcode. If provided instead of a UPRN, the Kamma API will attempt to derive the corresponding UPRN for the supplied address. As a result, the more components of the address that are provided the more likely an accurate match to a UPRN will be able to be determined. At a bare minimum the property name or number, building name (if present), street name, locality or post town and postcode should be provided as part of the address.

An address should be passed to the Kamma API as a string prefixed with the kamma:address: namespace and predicate and with the full address MIME or URL encoded.

Authenticating requests

X-SSO-API-KEY: [example-api-key]
Content-Type: application/json
Accept: application/json

This API is authenticated by sending a X-SSO-API-Key header with a value set to your supplied API key.

You must also send a X-SSO-Service-Key header with a value set to your supplied service key.

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

If an invalid API key is specified or the API key is missing, an HTTP status of 401 Unauthorized will be returned in the response headers.

EPC Checker Methods

Current Identifier EPC Status

requires authentication

The EPC Checker Methods return information on EPCs for the subject property.

Example request:

curl --request GET \
    --get "https://kamma.api.kammadata.com/api/properties/epc-check/geoplace:uprn:100023433011" \
    --header "X-SSO-API-Key: {{KAMMA_SSO_API_KEY}}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://kamma.api.kammadata.com/api/properties/epc-check/geoplace:uprn:100023433011"
);

const headers = {
    "X-SSO-API-Key": "{{KAMMA_SSO_API_KEY}}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://kamma.api.kammadata.com/api/properties/epc-check/geoplace:uprn:100023433011';
$response = $client->get(
    $url,
    [
        'headers' => [
            'X-SSO-API-Key' => '{{KAMMA_SSO_API_KEY}}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://kamma.api.kammadata.com/api/properties/epc-check/geoplace:uprn:100023433011'
headers = {
  'X-SSO-API-Key': '{{KAMMA_SSO_API_KEY}}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Success):


{
    "result": {
        "certificate": {
            "uprn": 100011623123,
            "address1": "6, Ashmeade",
            "address2": "Hale Barns",
            "post_town": "ALTRINCHAM",
            "postcode": "WA15 0DB",
            "building_reference_number": 4251743578,
            "current_energy_rating": "C",
            "potential_energy_rating": "B",
            "current_energy_efficiency": 74,
            "potential_energy_efficiency": 84,
            "property_type": "House",
            "built_form": "Detached",
            "inspection_date": "2017-08-15",
            "lodgement_date": "2017-08-15",
            "transaction_type": "marketed sale",
            "environment_impact_current": 66,
            "environment_impact_potential": 80,
            "energy_consumption_current": 165,
            "energy_consumption_potential": 96,
            "co2_emissions_current": 5.6,
            "co2_emiss_curr_per_floor_area": 30,
            "co2_emissions_potential": 3.3,
            "lighting_cost_current": 156,
            "lighting_cost_potential": 92,
            "heating_cost_current": 1015,
            "heating_cost_potential": 769,
            "hot_water_cost_current": 226,
            "hot_water_cost_potential": 80,
            "total_floor_area": 186,
            "energy_tariff": "Single",
            "mains_gas_flag": "Y",
            "main_heating_controls": "2104",
            "multi_glaze_proportion": 90,
            "glazed_type": "double glazing installed before 2002",
            "glazed_area": "Normal",
            "extension_count": "1",
            "number_habitable_rooms": 7,
            "number_heated_rooms": 7,
            "low_energy_lighting": 30,
            "number_open_fireplaces": 0,
            "hotwater_description": "From main system",
            "hot_water_energy_eff": "Good",
            "hot_water_env_eff": "Good",
            "floor_description": "Solid, no insulation (assumed)",
            "windows_description": "Mostly double glazing",
            "windows_energy_eff": "Average",
            "windows_env_eff": "Average",
            "walls_description": "Cavity wall, filled cavity",
            "walls_energy_eff": "Good",
            "walls_env_eff": "Good",
            "secondheat_description": "Room heaters, dual fuel (mineral and wood)",
            "roof_description": "Pitched, 270 mm loft insulation",
            "roof_energy_eff": "Good",
            "roof_env_eff": "Good",
            "mainheat_description": "Boiler and radiators, mains gas",
            "mainheat_energy_eff": "Good",
            "mainheat_env_eff": "Good",
            "mainheatcont_description": "Programmer and room thermostat",
            "mainheatc_energy_eff": "Average",
            "mainheatc_env_eff": "Average",
            "lighting_description": "Low energy lighting in 30% of fixed outlets",
            "lighting_energy_eff": "Average",
            "lighting_env_eff": "Average",
            "main_fuel": "mains gas (not community)",
            "wind_turbine_count": 0,
            "solar_water_heating_flag": "N",
            "mechanical_ventilation": "natural",
            "address": "6, Ashmeade, Hale Barns",
            "local_authority_label": "Trafford",
            "constituency_label": "Altrincham and Sale West",
            "construction_age_band": "England and Wales: 1983-1990",
            "lodgement_datetime": "2017-08-15T19:03:44+00:00",
            "tenure": "owner-occupied"
        },
        "recommendations": [
            {
                "item_text": "Solid floor insulation",
                "indicative_cost": [
                    4000,
                    6000
                ]
            },
            {
                "item_text": "Increase hot water cylinder insulation",
                "indicative_cost": [
                    15,
                    30
                ]
            },
            {
                "item_text": "Low energy lighting for all fixed outlets",
                "indicative_cost": [
                    70
                ]
            },
            {
                "item_text": "Upgrading heating controls",
                "indicative_cost": [
                    350,
                    450
                ]
            },
            {
                "item_text": "Replace boiler with new condensing boiler",
                "indicative_cost": [
                    2200,
                    3000
                ]
            },
            {
                "item_text": "Solar water heating",
                "indicative_cost": [
                    4000,
                    6000
                ]
            },
            {
                "item_text": "Replacement glazing units",
                "indicative_cost": [
                    1000,
                    1400
                ]
            }
        ]
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (400, Invalid Identifier token):


{
    "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"
}

Example response (404, Address resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 201001,
    "description": "The address resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (404, EPC resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 203001,
    "description": "The EPC resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (500, System error):


{
    "status": 500,
    "message": "Internal Server error",
    "code": 201002,
    "description": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

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

Headers

X-SSO-API-Key

Example: {{KAMMA_SSO_API_KEY}}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

identifier string

A property identifier for the required property; either a Kamma Property Id, a UPRN or an address can be used. Example: geoplace:uprn:100023433011

Response

Response Fields

response_id string

The unique id of API request

result object

The EPC object. For full description see EPC Schema.

certificate object

Data from the EPC

recommendations object[]

List of retrofit improvement recommendations from the EPC

Legislation Checker Methods

The Determination Checker Methods return information on the licensing schemes and consultations that the subject property geographically sits within. This will not give you the exact licence needed (see “Property Methods” for that) as that is dependent on the occupancy profile of the property (i.e. how many people are occupying it).

This also includes the same information on HMO (C3 -> C4) Article 4 Directions.

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

requires authentication

Example request:

curl --request GET \
    --get "https://kamma.api.kammadata.com/api/properties/determination-check/geoplace:uprn:100023433011" \
    --header "X-SSO-API-Key: {{KAMMA_SSO_API_KEY}}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://kamma.api.kammadata.com/api/properties/determination-check/geoplace:uprn:100023433011"
);

const headers = {
    "X-SSO-API-Key": "{{KAMMA_SSO_API_KEY}}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://kamma.api.kammadata.com/api/properties/determination-check/geoplace:uprn:100023433011';
$response = $client->get(
    $url,
    [
        'headers' => [
            'X-SSO-API-Key' => '{{KAMMA_SSO_API_KEY}}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://kamma.api.kammadata.com/api/properties/determination-check/geoplace:uprn:100023433011'
headers = {
  'X-SSO-API-Key': '{{KAMMA_SSO_API_KEY}}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Success):


{
    "result": {
        "advice": {
            "mandatory": "A Mandatory HMO scheme covers the whole of Westminster. This scheme is permanent and includes and includes all HMOs with at least 5 people on 1 storey since October 1st 2018.",
            "additional": "There are no active Additional licensing schemes at this location right now.",
            "selective": "There are no active Additional licensing schemes at this location right now.",
            "article4": "There are no active Article 4 directions at this location right now.",
            "future": "The next Article 4 direction is planned for October 10th 2018."
        },
        "planning": [
            {
                "id": 123,
                "name": "",
                "type": "article4",
                "state": {
                    "in": false,
                    "active": false,
                    "future": true,
                    "expired": null,
                    "consultation": false
                },
                "criteria": {
                    "date_start": "2018-10-01T00:00:00.000Z",
                    "date_end": null,
                    "above_commercial": null,
                    "property_category": null,
                    "restrict_from": "C3",
                    "restrict_to": "C4"
                },
                "link": "https://www.royalgreenwich.gov.uk/info/200191/planning_policy_and_strategy/1793/article_4_direction_areas/2"
            }
        ],
        "schemes": [
            {
                "id": 123,
                "name": "",
                "type": "mandatory",
                "state": {
                    "in": true,
                    "active": true,
                    "future": false,
                    "expired": null,
                    "consultation": false
                },
                "criteria": {
                    "date_start": "2006-04-01T00:00:00.000Z",
                    "date_end": null,
                    "above_commercial": 0,
                    "configurations": [
                        {
                            "households": 2,
                            "people": 5,
                            "storeys": 1
                        }
                    ]
                },
                "link": "https://www.royalgreenwich.gov.uk/info/200290/multiple_occupancy_homes/937/apply_for_a_hmo_licence"
            }
        ]
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (400, Invalid PropertyToken token):


{
    "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"
}

Example response (404, Address resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 201001,
    "description": "The address resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (404, Licence determination resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 202001,
    "description": "The licence determination resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (500, System error):


{
    "status": 500,
    "message": "Internal Server error",
    "code": 201002,
    "description": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

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

Headers

X-SSO-API-Key

Example: {{KAMMA_SSO_API_KEY}}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

identifier string

A property identifier for the required property; either a Kamma Property Id, a UPRN or an address can be used. Example: geoplace:uprn:100023433011

Response

Response Fields

response_id string

The unique id of this API request

result object

Licensing determination result. For full description see Determination Schema.

advice object[]

List of licensing schemes that cover the subject property in plain English textual format. N.B. this refers to the geographic location of the property, not its occupancy profile

planning object[]

List of HMO Article 4 Directions that cover the subject property. N.B. this refers to the geographic location of the property, not its HMO status

schemes object[]

List of licensing schemes that cover the subject property broken into various data fields. N.B. this refers to the geographic location of the property, not its occupancy profile

Licence Register Methods

Current Identifier Licensing Status

requires authentication

The Licensing Checker Methods return information on applicable licensing schemes to the subject property given its occupancy profile and other relevant property data.

Example request:

curl --request GET \
    --get "https://kamma.api.kammadata.com/api/properties/licensing-check/geoplace:uprn:100023433011" \
    --header "X-SSO-API-Key: {{KAMMA_SSO_API_KEY}}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://kamma.api.kammadata.com/api/properties/licensing-check/geoplace:uprn:100023433011"
);

const headers = {
    "X-SSO-API-Key": "{{KAMMA_SSO_API_KEY}}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://kamma.api.kammadata.com/api/properties/licensing-check/geoplace:uprn:100023433011';
$response = $client->get(
    $url,
    [
        'headers' => [
            'X-SSO-API-Key' => '{{KAMMA_SSO_API_KEY}}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://kamma.api.kammadata.com/api/properties/licensing-check/geoplace:uprn:100023433011'
headers = {
  'X-SSO-API-Key': '{{KAMMA_SSO_API_KEY}}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Success):


{
    "result": {
        "current": {
            "hmo": true
        },
        "historic": {
            "hmo": true
        },
        "licences": [
            {
                "type": "additional",
                "address": "52, Crown Street, London, WC1E 6JP",
                "licencee": "Mr John Smith",
                "people": 0,
                "households": 0,
                "status": "approved",
                "date_start": "2018-05-09",
                "date_end": "2023-05-09"
            },
            {
                "type": "additional",
                "address": "52, Crown Street, London, WC1E 6JP",
                "licencee": "Mr John Smith",
                "people": 5,
                "households": 5,
                "status": "approved",
                "date_start": "2018-05-09",
                "date_end": "2023-05-09"
            }
        ]
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (400, Invalid PropertyToken token):


{
    "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"
}

Example response (404, Resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 102000,
    "description": "The api resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (500, System error):


{
    "status": 500,
    "message": "Internal Server error",
    "code": 201002,
    "description": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

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

Headers

X-SSO-API-Key

Example: {{KAMMA_SSO_API_KEY}}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

identifier string

A property identifier for the required property; either a Kamma Property Id, a UPRN or an address can be used. Example: geoplace:uprn:100023433011

Response

Response Fields

response_id string

The unique id of api request

result object

The licensing object. For full description see Licensing Schema.

current object

Data and information on active licences at the subject property address from council licence registers

historic object

Data and information on historic licences at the subject property address from council licence registers

licences

Data and information on licences at the subject property address from council licence registers

Property Methods

The Property Methods return information on the licensing determination and requirement for the subject property given its occupancy profile and other relevant property data. These are the most commonly used Methods in the Kamma API.

Property Check

requires authentication

When requested with a valid identifier, this resource returns the current property details and the compliance status for the property associated with the token.

Example request:

curl --request GET \
    --get "https://kamma.api.kammadata.com/api/properties/property-check/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0" \
    --header "X-SSO-API-Key: {{KAMMA_SSO_API_KEY}}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://kamma.api.kammadata.com/api/properties/property-check/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0"
);

const headers = {
    "X-SSO-API-Key": "{{KAMMA_SSO_API_KEY}}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://kamma.api.kammadata.com/api/properties/property-check/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0';
$response = $client->get(
    $url,
    [
        'headers' => [
            'X-SSO-API-Key' => '{{KAMMA_SSO_API_KEY}}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://kamma.api.kammadata.com/api/properties/property-check/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0'
headers = {
  'X-SSO-API-Key': '{{KAMMA_SSO_API_KEY}}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200, Success):


{
    "result": {
        "id": "kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0",
        "external_reference": "TEST_123",
        "address": "1 Tuscan Road, Greenwich, London, SE18 1SY",
        "postcode": "SE18 1SY",
        "council": "Greenwich",
        "council_websites": [
            "https://www.royalgreenwich.gov.uk",
            "https://committees.royalgreenwich.gov.uk"
        ],
        "advice_text_current": "Licensing is currently required.",
        "advice_text_future": "Licensing will be required for a scheme or direction that starts in the future.",
        "requires": {
            "current": {
                "mandatory": false,
                "additional": true,
                "selective": false,
                "article4": true
            },
            "future": {
                "mandatory": false,
                "additional": false,
                "selective": true,
                "article4": false
            },
            "future_start_date": {
                "mandatory": null,
                "additional": null,
                "selective": "2022-10-01T00:00:00.000Z",
                "article4": null
            }
        },
        "approved_scheme": {
            "id": null,
            "type": null,
            "date_start": null,
            "date_end": null
        },
        "metadata": {
            "people": 3,
            "households": 2,
            "storeys": {
                "external": null,
                "internal": null
            },
            "rooms": null,
            "above_commercial": null,
            "property_category": null,
            "property_class": "unknown",
            "notes": ""
        },
        "analysis": [
            "Additional scheme requirements met",
            "Selective Scheme upcoming",
            "Use Class: C4"
        ],
        "actions": [
            "This selective scheme is due to start, early bird discounts for applications may apply.",
            "Apply for Additional licence",
            "Planning permission required"
        ],
        "regulations": [
            {
                "id": 126,
                "type": "mandatory",
                "confidence": 100,
                "date_start": "2006-04-01T00:00:00.000Z",
                "date_end": null,
                "link": "https://www.royalgreenwich.gov.uk/info/200290/multiple_occupancy_homes/937/apply_for_a_hmo_licence",
                "consultation": 0
            },
            {
                "id": 127,
                "type": "additional",
                "confidence": 100,
                "date_start": "2017-10-01T00:00:00.000Z",
                "date_end": "2022-09-30T23:59:59.000Z",
                "link": "https://www.royalgreenwich.gov.uk/info/200290/multiple_occupancy_homes/937/apply_for_a_hmo_licence",
                "consultation": 0
            },
            {
                "id": 806,
                "type": "selective",
                "confidence": 100,
                "date_start": "2022-10-01T00:00:00.000Z",
                "date_end": "2027-09-30T23:59:59.000Z",
                "link": "https://committees.royalgreenwich.gov.uk/CalendarofMeetings/tabid/70/ctl/ViewMeetingPublic/mid/397/Meeting/2320/Committee/72/SelectedTab/Documents/Default.aspx",
                "consultation": 0
            },
            {
                "id": 10,
                "type": "article4",
                "confidence": null,
                "date_start": "2018-10-01T00:00:00.000Z",
                "date_end": null,
                "link": "https://www.royalgreenwich.gov.uk/info/200191/planning_policy_and_strategy/1793/article_4_direction_areas/2",
                "consultation": 0
            }
        ],
        "licence_application": {
            "status": null,
            "application": {
                "type": null,
                "date_start": null,
                "date_end": null,
                "max_people": null,
                "max_households": null,
                "reference": null
            }
        },
        "planning_application": {
            "status": null,
            "application": {
                "type": null
            }
        }
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response_id": "409228f9-1583-4993-8efe-25a073ba757d"
}

Example response (400, Invalid PropertyToken token):


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

Example response (404, Property resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 205001,
    "description": "The property resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (500, System error):


{
    "status": 500,
    "message": "Internal Server error",
    "code": 201002,
    "description": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

response_id string

The unique id of api request

result object

The success state. For full description see Identifier Schema.

id string

The property unique identifier

external_reference string

The external property reference

address string

The property address

postcode string

The property postcode

council string

The council that the property sits within

council_websites string[]

List of council licensing website links

active_text_current string

Advice text that states if a licence is currently required

active_text_future string

Advice text that states if a licence will be required in relation to a scheme that is designated to start at a future date

requires object

Current and future requirements

approved_scheme object

Approved scheme details

metadata object

Additional information about property

analysis string[]

Advice on the type of analysis that should be performed

actions string[]

Advice on the actions that should be performed

regulations object[]

The direct regulatory information of the schemes that apply to the property

licence_application object

Licence application

planning_application object

Planning application

Property Create

requires authentication

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.

A full street level address, including postcode, or a UPRN, must be provided for this endpoint in the address field of the request body. If an address is provided that does not contain the postcode or a UPRN is provided, the postcode must also be provided in the postcode field of the request body.

Example request:

curl --request POST \
    "https://kamma.api.kammadata.com/api/properties/create" \
    --header "X-SSO-API-Key: {{KAMMA_SSO_API_KEY}}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"address\": \"52 Crown Street, London, WC1E 6JP\",
    \"postcode\": \"WC1E 6JP\",
    \"external_reference\": \"ref-12345\",
    \"people\": 5,
    \"households\": 3,
    \"storeys_internal\": 2,
    \"storeys_external\": 2,
    \"above_commercial\": 1,
    \"rooms\": 3,
    \"rent\": 360000,
    \"property_category\": \"s257\",
    \"property_class\": \"flat\",
    \"notes\": \"\",
    \"licence_status\": \"inprogress\",
    \"licence_type\": \"unknown\",
    \"licence_date_start\": \"2020-01-25\",
    \"licence_date_end\": \"2025-01-25\",
    \"licence_max_people\": 5,
    \"licence_max_households\": 20,
    \"licence_reference\": \"ref-12345\",
    \"planning_status\": \"applied\",
    \"planning_reference\": \"ref-12345\"
}"

const url = new URL(
    "https://kamma.api.kammadata.com/api/properties/create"
);

const headers = {
    "X-SSO-API-Key": "{{KAMMA_SSO_API_KEY}}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "address": "52 Crown Street, London, WC1E 6JP",
    "postcode": "WC1E 6JP",
    "external_reference": "ref-12345",
    "people": 5,
    "households": 3,
    "storeys_internal": 2,
    "storeys_external": 2,
    "above_commercial": 1,
    "rooms": 3,
    "rent": 360000,
    "property_category": "s257",
    "property_class": "flat",
    "notes": "",
    "licence_status": "inprogress",
    "licence_type": "unknown",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 20,
    "licence_reference": "ref-12345",
    "planning_status": "applied",
    "planning_reference": "ref-12345"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://kamma.api.kammadata.com/api/properties/create';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-SSO-API-Key' => '{{KAMMA_SSO_API_KEY}}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'address' => '52 Crown Street, London, WC1E 6JP',
            'postcode' => 'WC1E 6JP',
            'external_reference' => 'ref-12345',
            'people' => 5,
            'households' => 3,
            'storeys_internal' => 2,
            'storeys_external' => 2,
            'above_commercial' => 1,
            'rooms' => 3,
            'rent' => 360000,
            'property_category' => 's257',
            'property_class' => 'flat',
            'notes' => '',
            'licence_status' => 'inprogress',
            'licence_type' => 'unknown',
            'licence_date_start' => '2020-01-25',
            'licence_date_end' => '2025-01-25',
            'licence_max_people' => 5,
            'licence_max_households' => 20,
            'licence_reference' => 'ref-12345',
            'planning_status' => 'applied',
            'planning_reference' => 'ref-12345',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://kamma.api.kammadata.com/api/properties/create'
payload = {
    "address": "52 Crown Street, London, WC1E 6JP",
    "postcode": "WC1E 6JP",
    "external_reference": "ref-12345",
    "people": 5,
    "households": 3,
    "storeys_internal": 2,
    "storeys_external": 2,
    "above_commercial": 1,
    "rooms": 3,
    "rent": 360000,
    "property_category": "s257",
    "property_class": "flat",
    "notes": "",
    "licence_status": "inprogress",
    "licence_type": "unknown",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 20,
    "licence_reference": "ref-12345",
    "planning_status": "applied",
    "planning_reference": "ref-12345"
}
headers = {
  'X-SSO-API-Key': '{{KAMMA_SSO_API_KEY}}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200, Success):


{
    "result": {
        "id": "kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0",
        "external_reference": "TEST_123",
        "address": "1 Tuscan Road, Greenwich, London, SE18 1SY",
        "postcode": "SE18 1SY",
        "council": "Greenwich",
        "council_websites": [
            "https://www.royalgreenwich.gov.uk",
            "https://committees.royalgreenwich.gov.uk"
        ],
        "advice_text_current": "Licensing is currently required.",
        "advice_text_future": "Licensing will be required for a scheme or direction that starts in the future.",
        "requires": {
            "current": {
                "mandatory": false,
                "additional": true,
                "selective": false,
                "article4": true
            },
            "future": {
                "mandatory": false,
                "additional": false,
                "selective": true,
                "article4": false
            },
            "future_start_date": {
                "mandatory": null,
                "additional": null,
                "selective": "2022-10-01T00:00:00.000Z",
                "article4": null
            }
        },
        "approved_scheme": {
            "id": null,
            "type": null,
            "date_start": null,
            "date_end": null
        },
        "metadata": {
            "people": 3,
            "households": 2,
            "storeys": {
                "external": null,
                "internal": null
            },
            "rooms": null,
            "above_commercial": null,
            "property_category": null,
            "property_class": "unknown",
            "notes": ""
        },
        "analysis": [
            "Additional scheme requirements met",
            "Selective Scheme upcoming",
            "Use Class: C4"
        ],
        "actions": [
            "This selective scheme is due to start, early bird discounts for applications may apply.",
            "Apply for Additional licence",
            "Planning permission required"
        ],
        "regulations": [
            {
                "id": 126,
                "type": "mandatory",
                "confidence": 100,
                "date_start": "2006-04-01T00:00:00.000Z",
                "date_end": null,
                "link": "https://www.royalgreenwich.gov.uk/info/200290/multiple_occupancy_homes/937/apply_for_a_hmo_licence",
                "consultation": 0
            },
            {
                "id": 127,
                "type": "additional",
                "confidence": 100,
                "date_start": "2017-10-01T00:00:00.000Z",
                "date_end": "2022-09-30T23:59:59.000Z",
                "link": "https://www.royalgreenwich.gov.uk/info/200290/multiple_occupancy_homes/937/apply_for_a_hmo_licence",
                "consultation": 0
            },
            {
                "id": 806,
                "type": "selective",
                "confidence": 100,
                "date_start": "2022-10-01T00:00:00.000Z",
                "date_end": "2027-09-30T23:59:59.000Z",
                "link": "https://committees.royalgreenwich.gov.uk/CalendarofMeetings/tabid/70/ctl/ViewMeetingPublic/mid/397/Meeting/2320/Committee/72/SelectedTab/Documents/Default.aspx",
                "consultation": 0
            },
            {
                "id": 10,
                "type": "article4",
                "confidence": null,
                "date_start": "2018-10-01T00:00:00.000Z",
                "date_end": null,
                "link": "https://www.royalgreenwich.gov.uk/info/200191/planning_policy_and_strategy/1793/article_4_direction_areas/2",
                "consultation": 0
            }
        ],
        "licence_application": {
            "status": null,
            "application": {
                "type": null,
                "date_start": null,
                "date_end": null,
                "max_people": null,
                "max_households": null,
                "reference": null
            }
        },
        "planning_application": {
            "status": null,
            "application": {
                "type": null
            }
        }
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response_id": "409228f9-1583-4993-8efe-25a073ba757d"
}

Example response (400, Request body validation failed):


{
    "status": 400,
    "message": "Bad Request",
    "code": 103000,
    "description": "Validation error: The address field is required.",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (403, Account limit reached):


{
    "status": 403,
    "message": "Forbidden",
    "code": 600001,
    "description": "Account limit reached. Speak to Customer Support for assistance",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (409, Resource Conflict):


{
    "status": 409,
    "message": "Resource Conflict",
    "code": 700001,
    "description": "Request cannot complete due to conflicting operation.",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (500, System error):


{
    "status": 500,
    "message": "Internal Server error",
    "code": 201002,
    "description": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/properties/create

Headers

X-SSO-API-Key

Example: {{KAMMA_SSO_API_KEY}}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

address string

A full street level address or UPRN. Example: 52 Crown Street, London, WC1E 6JP

postcode string

The property’s postcode. Example: WC1E 6JP

external_reference string optional

Your own external reference. Example: ref-12345

people integer optional

Number of people living in the property. Example: 5

households integer optional

Number of households living in the property. Example: 3

storeys_internal integer optional

Number of internal storeys of the building, e.g. a flat above a shop = 2 storeys. Example: 2

storeys_external integer optional

Number of external storeys of the building, e.g. a flat above a shop = 2 storeys. Example: 2

above_commercial integer optional

Is the property above commercial premises?. Example: 1

Must be one of:

rooms integer optional

Number of bedrooms in the property. Example: 3

rent integer optional

Amount of rent paid, weekly in pence. Example: 360000

property_category string optional

This is the category of the property under the Housing Act 2004. In most cases this field can be left as null. Example: s257

Must be one of:

single
s254
s257
licenseable

property_class string optional

Knowing the type of property will allow us to assess compliance in terms of residential planning permission required across the UK. Example: flat

Must be one of:

house
flat

notes string optional

licence_status string optional

Example: inprogress

Must be one of:

applied
inprogress
requested

licence_type string optional

This is the result of the Kamma platform's assessment. Example: unknown

Must be one of:

unknown
mandatory
additional
selective
none

licence_date_start string optional

Licence start date. Must be a valid date in the format Y-m-d. Example: 2020-01-25

licence_date_end string optional

Licence end date. Must be a valid date in the format Y-m-d. Example: 2025-01-25

licence_max_people integer optional

Both Mandatory and Additional licensing will impose a limit on the number of occupants. Example: 5

licence_max_households integer optional

Example: 20

licence_reference string optional

Optional; licence reference issued by the Local Authority. Example: ref-12345

planning_status string optional

Example: applied

Must be one of:

applied
inprogress
requested

planning_reference string optional

Example: ref-12345

Response

Response Fields

response_id string

The unique id of api request

result object

The success state. For full description see Identifier Schema.

id string

The Kamma Property Id

external_reference string

The external property reference

address string

The property address

postcode string

The property postcode

council string

The council that the property sits within

council_websites string[]

List of council licensing website links

active_text string

Advice text that states if a licence is currently required

requires object

Current and future requirements

approved_scheme object

Approved scheme details

metadata object

Additional information about property

analysis string[]

Advice on the type of analysis that should be performed

actions string[]

Advice on the actions that should be performed

regulations object[]

The direct regulatory information of the schemes that apply to the property

licence_application object

Licence application

planning_application object

Planning application

Property Sync

requires authentication

When requested with a valid identifier and payload, the property associated with the token is updated in the KammaData system.

Example request:

curl --request PUT \
    "https://kamma.api.kammadata.com/api/properties/sync/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0" \
    --header "X-SSO-API-Key: {{KAMMA_SSO_API_KEY}}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"address\": \"52 Crown Street, London, WC1E 6JP\",
    \"postcode\": \"WC1E 6JP\",
    \"external_reference\": \"ref-12345\",
    \"people\": 5,
    \"households\": 3,
    \"storeys_internal\": 2,
    \"storeys_external\": 2,
    \"above_commercial\": 1,
    \"rooms\": 3,
    \"rent\": 360000,
    \"property_category\": \"single\",
    \"property_class\": \"house\",
    \"notes\": \"\",
    \"licence_status\": \"inprogress\",
    \"licence_type\": \"none\",
    \"licence_date_start\": \"2020-01-25\",
    \"licence_date_end\": \"2025-01-25\",
    \"licence_max_people\": 5,
    \"licence_max_households\": 11,
    \"licence_reference\": \"ref-12345\",
    \"planning_status\": \"applied\",
    \"planning_reference\": \"ref-12345\"
}"

const url = new URL(
    "https://kamma.api.kammadata.com/api/properties/sync/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0"
);

const headers = {
    "X-SSO-API-Key": "{{KAMMA_SSO_API_KEY}}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "address": "52 Crown Street, London, WC1E 6JP",
    "postcode": "WC1E 6JP",
    "external_reference": "ref-12345",
    "people": 5,
    "households": 3,
    "storeys_internal": 2,
    "storeys_external": 2,
    "above_commercial": 1,
    "rooms": 3,
    "rent": 360000,
    "property_category": "single",
    "property_class": "house",
    "notes": "",
    "licence_status": "inprogress",
    "licence_type": "none",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 11,
    "licence_reference": "ref-12345",
    "planning_status": "applied",
    "planning_reference": "ref-12345"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://kamma.api.kammadata.com/api/properties/sync/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0';
$response = $client->put(
    $url,
    [
        'headers' => [
            'X-SSO-API-Key' => '{{KAMMA_SSO_API_KEY}}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'address' => '52 Crown Street, London, WC1E 6JP',
            'postcode' => 'WC1E 6JP',
            'external_reference' => 'ref-12345',
            'people' => 5,
            'households' => 3,
            'storeys_internal' => 2,
            'storeys_external' => 2,
            'above_commercial' => 1,
            'rooms' => 3,
            'rent' => 360000,
            'property_category' => 'single',
            'property_class' => 'house',
            'notes' => '',
            'licence_status' => 'inprogress',
            'licence_type' => 'none',
            'licence_date_start' => '2020-01-25',
            'licence_date_end' => '2025-01-25',
            'licence_max_people' => 5,
            'licence_max_households' => 11,
            'licence_reference' => 'ref-12345',
            'planning_status' => 'applied',
            'planning_reference' => 'ref-12345',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://kamma.api.kammadata.com/api/properties/sync/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0'
payload = {
    "address": "52 Crown Street, London, WC1E 6JP",
    "postcode": "WC1E 6JP",
    "external_reference": "ref-12345",
    "people": 5,
    "households": 3,
    "storeys_internal": 2,
    "storeys_external": 2,
    "above_commercial": 1,
    "rooms": 3,
    "rent": 360000,
    "property_category": "single",
    "property_class": "house",
    "notes": "",
    "licence_status": "inprogress",
    "licence_type": "none",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 11,
    "licence_reference": "ref-12345",
    "planning_status": "applied",
    "planning_reference": "ref-12345"
}
headers = {
  'X-SSO-API-Key': '{{KAMMA_SSO_API_KEY}}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PUT', url, headers=headers, json=payload)
response.json()

Example response (200, Success):


{
    "result": {
        "id": "kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0",
        "external_reference": "TEST_123",
        "address": "1 Tuscan Road, Greenwich, London, SE18 1SY",
        "postcode": "SE18 1SY",
        "council": "Greenwich",
        "council_websites": [
            "https://www.royalgreenwich.gov.uk",
            "https://committees.royalgreenwich.gov.uk"
        ],
        "advice_text_current": "Licensing is currently required.",
        "advice_text_future": "Licensing will be required for a scheme or direction that starts in the future.",
        "requires": {
            "current": {
                "mandatory": false,
                "additional": true,
                "selective": false,
                "article4": true
            },
            "future": {
                "mandatory": false,
                "additional": false,
                "selective": true,
                "article4": false
            },
            "future_start_date": {
                "mandatory": null,
                "additional": null,
                "selective": "2022-10-01T00:00:00.000Z",
                "article4": null
            }
        },
        "approved_scheme": {
            "id": null,
            "type": null,
            "date_start": null,
            "date_end": null
        },
        "metadata": {
            "people": 3,
            "households": 2,
            "storeys": {
                "external": null,
                "internal": null
            },
            "rooms": null,
            "above_commercial": null,
            "property_category": null,
            "property_class": "unknown",
            "notes": ""
        },
        "analysis": [
            "Additional scheme requirements met",
            "Selective Scheme upcoming",
            "Use Class: C4"
        ],
        "actions": [
            "This selective scheme is due to start, early bird discounts for applications may apply.",
            "Apply for Additional licence",
            "Planning permission required"
        ],
        "regulations": [
            {
                "id": 126,
                "type": "mandatory",
                "confidence": 100,
                "date_start": "2006-04-01T00:00:00.000Z",
                "date_end": null,
                "link": "https://www.royalgreenwich.gov.uk/info/200290/multiple_occupancy_homes/937/apply_for_a_hmo_licence",
                "consultation": 0
            },
            {
                "id": 127,
                "type": "additional",
                "confidence": 100,
                "date_start": "2017-10-01T00:00:00.000Z",
                "date_end": "2022-09-30T23:59:59.000Z",
                "link": "https://www.royalgreenwich.gov.uk/info/200290/multiple_occupancy_homes/937/apply_for_a_hmo_licence",
                "consultation": 0
            },
            {
                "id": 806,
                "type": "selective",
                "confidence": 100,
                "date_start": "2022-10-01T00:00:00.000Z",
                "date_end": "2027-09-30T23:59:59.000Z",
                "link": "https://committees.royalgreenwich.gov.uk/CalendarofMeetings/tabid/70/ctl/ViewMeetingPublic/mid/397/Meeting/2320/Committee/72/SelectedTab/Documents/Default.aspx",
                "consultation": 0
            },
            {
                "id": 10,
                "type": "article4",
                "confidence": null,
                "date_start": "2018-10-01T00:00:00.000Z",
                "date_end": null,
                "link": "https://www.royalgreenwich.gov.uk/info/200191/planning_policy_and_strategy/1793/article_4_direction_areas/2",
                "consultation": 0
            }
        ],
        "licence_application": {
            "status": null,
            "application": {
                "type": null,
                "date_start": null,
                "date_end": null,
                "max_people": null,
                "max_households": null,
                "reference": null
            }
        },
        "planning_application": {
            "status": null,
            "application": {
                "type": null
            }
        }
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response_id": "409228f9-1583-4993-8efe-25a073ba757d"
}

Example response (400, Invalid PropertyToken token):


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

Example response (400, Request body validation failed):


{
    "status": 400,
    "message": "Bad Request",
    "code": 103000,
    "description": "Validation error: The address field is required.",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (404, Property resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 205001,
    "description": "The property resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (409, Resource Conflict):


{
    "status": 409,
    "message": "Resource Conflict",
    "code": 700001,
    "description": "Request cannot complete due to conflicting operation.",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (500, System error):


{
    "status": 500,
    "message": "Internal Server error",
    "code": 201002,
    "description": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

PUT api/properties/sync/{identifier}

Headers

X-SSO-API-Key

Example: {{KAMMA_SSO_API_KEY}}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

identifier string

A Kamma Property Id. Example: kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0

Body Parameters

address string

A full street level address or UPRN. Example: 52 Crown Street, London, WC1E 6JP

postcode string

The property’s postcode. Example: WC1E 6JP

external_reference string optional

Your own external reference. Example: ref-12345

people integer optional

Number of people living in the property. Example: 5

households integer optional

Number of households living in the property. Example: 3

storeys_internal integer optional

Number of internal storeys of the building, e.g. a flat above a shop = 2 storeys. Example: 2

storeys_external integer optional

Number of external storeys of the building, e.g. a flat above a shop = 2 storeys. Example: 2

above_commercial integer optional

Is the property above commercial premises?. Example: 1

Must be one of:

rooms integer optional

Number of bedrooms in the property. Example: 3

rent integer optional

Amount of rent paid, weekly in pence. Example: 360000

property_category string optional

This is the category of the property under the Housing Act 2004. In most cases this field can be left as null. Example: single

Must be one of:

single
s254
s257
licenseable

property_class string optional

Knowing the type of property will allow us to assess compliance in terms of residential planning permission required across the UK. Example: house

Must be one of:

house
flat

notes string optional

licence_status string optional

Example: inprogress

Must be one of:

applied
inprogress
requested

licence_type string optional

This is the result of the Kamma platform's assessment. Example: none

Must be one of:

unknown
mandatory
additional
selective
none

licence_date_start string optional

Licence start date. Must be a valid date in the format Y-m-d. Example: 2020-01-25

licence_date_end string optional

Licence end date. Must be a valid date in the format Y-m-d. Example: 2025-01-25

licence_max_people integer optional

Both Mandatory and Additional licensing will impose a limit on the number of occupants. Example: 5

licence_max_households integer optional

Example: 11

licence_reference string optional

Optional; licence reference issued by the Local Authority. Example: ref-12345

planning_status string optional

Example: applied

Must be one of:

applied
inprogress
requested

planning_reference string optional

Example: ref-12345

Response

Response Fields

response_id string

The unique id of api request

result object

The success state. For full description see Identifier Schema.

id string

The property unique identifier

external_reference string

The external property reference

address string

The property address

postcode string

The property postcode

council string

The property council

council_websites string[]

List of council websites

active_text string

Advice text

requires object

Current and future requirements

approved_scheme object

Approved scheme details

metadata object

Additional information about property

analysis string[]

Advice on the type of analysis that should be performed

actions string[]

Advice on the actions that should be performed

regulations object[]

The direct regulatory information of the schemes that apply to the property

licence_application object

Licence application

planning_application object

Planning application

Property Archive

requires authentication

When requested with a valid identifier, the property associated with the token is deleted from the KammaData system

Example request:

curl --request DELETE \
    "https://kamma.api.kammadata.com/api/properties/archive/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0" \
    --header "X-SSO-API-Key: {{KAMMA_SSO_API_KEY}}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://kamma.api.kammadata.com/api/properties/archive/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0"
);

const headers = {
    "X-SSO-API-Key": "{{KAMMA_SSO_API_KEY}}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://kamma.api.kammadata.com/api/properties/archive/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'X-SSO-API-Key' => '{{KAMMA_SSO_API_KEY}}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://kamma.api.kammadata.com/api/properties/archive/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0'
headers = {
  'X-SSO-API-Key': '{{KAMMA_SSO_API_KEY}}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

Example response (200, Success):


{
    "result": {
        "id": "kamma:property:ea357bde17331f4217bd7898c50175fa",
        "success": true
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (400, Invalid PropertyToken token):


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

Example response (404, Property resource not found):


{
    "status": 404,
    "message": "Not Found",
    "code": 205001,
    "description": "The property resource was not found",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (409, Resource Conflict):


{
    "status": 409,
    "message": "Resource Conflict",
    "code": 700001,
    "description": "Request cannot complete due to conflicting operation.",
    "response_id": "1234-1234-1234-1234-1234"
}

Example response (500, System error):


{
    "status": 500,
    "message": "Internal Server error",
    "code": 201002,
    "description": "The server encountered an unexpected condition that prevented it from fulfilling the request"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

response_id string

The unique id of api request

result object

The success state

id string

The property unique identifier

success boolean

Success state of the archive request

Schemas

Determination Schema

advice: object List of advice for each type
- mandatory: string Mandatory advice
- additional: string Additional advice
- selective: string Selective advice
- article4: string Article4 advice
- future: string Future advice
planning: array List of planning directives
- id: int The unique id of the planning directive
- name: string Name of the planning directive
- type: string Type of the planning directive
- state object Planning directive state
  - in: bool Is the property located in a planning area
  - active: bool Is the planning active
  - future: bool Is the planning in the future
  - expired: bool Is the planning expired
  - consultation: bool Is the planning undergoing a consultation
- criteria: object Planning directive criteria
  - date_start: string Date planning directive started
  - date_end: string|null Date planning directive ended or is due to end
  - above_commercial: int|null Whether planning directive is for above commercial properties
  - property_category:string, Property category to which the restrictions apply
  - restrict_from: string, Use class from which the restrictions apply
  - restrict_to: string Use class to which the restrictions apply
- link: string Link to planning directive source
schemes: array List of schemes
- id: int The unique id of the scheme
- name: string Name of the scheme
- type: string Type of the scheme, one of mandatory, additional, or selective
- state object scheme state
  - in: bool Ss the property located in a scheme area
  - active: bool Is the scheme active
  - future: bool Is the scheme in the future
  - expired: bool Is the scheme expired
  - consultation: bool Is the scheme undergoing a consultation
- criteria: object scheme criteria
  - date_start: string Date scheme started
  - date_end: string|null Date scheme ended or is due to end
  - above_commercial: int|null Whether scheme is for above commercial properties
  - configurations: object
    - households: int Total number of households
    - people: int Total number of people
    - storeys: int Total number of storeys
- link: string Link to scheme source

EPC Schema

certificate: object Details of the EPC certificate
- uprn: int UPRN
- address1: string First line of the address
- address2: string Second line of the address
- post_town: string The post town of the property
- postcode: string The postcode of the property
- building_reference_number: int Unique identifier for the property
- current_energy_rating: string Current energy rating converted into a linear 'A to G' rating (where A is the most energy efficient and G is the least energy efficient)
- potential_energy_rating: string Estimated potential energy rating converted into a linear 'A to G' rating (where A is the most energy efficient and G is the least energy efficient)
- current_energy_efficiency: int Based on cost of energy, i.e. energy required for space heating, water heating and lighting [in kWh/year] multiplied by fuel costs. (£/m²/year where cost is derived from kWh)
- potential_energy_efficiency: int The potential energy efficiency rating of the property
- property_class: string Describes the type of property such as House, Flat, etc. This is the type differentiator for dwellings.
- built_form: string The building type of the Property e.g. Detached, Semi-Detached, Terrace etc. Together with the Property Type, the Build Form produces a structured description of the property.
- inspection_date: string The date that the inspection was actually carried out by the energy assessor
- lodgement_date:string Date lodged on the Energy Performance of Buildings Register
- transaction_type: string Type of transaction that triggered EPC. For example, one of: marketed sale; non-marketed sale; new-dwelling; rental; not sale or rental; assessment for Green Deal; following Green Deal; FIT application; none of the above; RHI application; ECO assessment. Where the reason for the assessment is unknown by the energy assessor the transaction type will be recorded as 'none of the above'. Transaction types may be changed over time.
- environment_impact_current: number The Environmental Impact Rating. A measure of the property's current impact on the environment in terms of carbon dioxide (CO₂) emissions. The higher the rating the lower the CO₂ emissions. (CO₂ emissions in tonnes / year)
- environment_impact_potential: number The potential Environmental Impact Rating. A measure of the property's potential impact on the environment in terms of carbon dioxide (CO₂) emissions after improvements have been carried out. The higher the rating the lower the CO₂ emissions. (CO₂ emissions in tonnes / year)
- energy_consumption_current: number Current estimated total energy consumption for the property in a 12 month period (kWh/m2). Displayed on EPC as the current primary energy use per square metre of floor area.
- energy_consumption_potential: number Estimated potential total energy consumption for the Property in a 12 month period. Value is Kilowatt Hours per Square Metre (kWh/m²)
- co2_emissions_current: number Current CO₂ emissions per year in tonnes/year
- co2_emiss_curr_per_floor_area: number CO₂ emissions per square metre floor area per year in kg/m²
- co2_emissions_potential: number Estimated value in Tonnes per Year of the total CO₂ emissions produced by the Property in 12 month period
- lighting_cost_current: number GBP. Current estimated annual energy costs for lighting the property.
- lighting_cost_potential: number GBP. Potential estimated annual energy costs for lighting the property after improvements have been made.
- heating_cost_current: number GBP. Current estimated annual energy costs for heating the property.
- heating_cost_potential: number GBP. Potential annual energy costs for heating the property after improvements have been made.
- hot_water_cost_current: number GBP. Current estimated annual energy costs for hot water.
- hot_water_cost_potential: number GBP. Potential estimated annual energy costs for hot water after improvements have been made.
- total_floor_area: number The total useful floor area is the total of all enclosed spaces measured to the internal face of the external walls, i.e. the gross floor area as measured in accordance with the guidance issued from time to time by the Royal Institute of Chartered Surveyors or by a body replacing that institution. (m²)
- energy_tariff: string Type of electricity tariff for the property, e.g. single.
- mains_gas_flag: string Whether mains gas is available. Yes means that there is a gas meter or a gas-burning appliance in the dwelling. A closed-off gas pipe does not count.
- main_heating_controls: string Type of main heating controls. Includes both main heating systems if there are two.
- multi_glaze_proportion: string The estimated banded range (e.g. 0% - 10%) of the total glazed area of the Property that is multiple glazed.
- glazed_type: string The type of glazing. From British Fenestration Rating Council or manufacturer declaration, one of; single; double; triple.
- glazed_area: _string Ranged estimate of the total glazed area of the Habitable Area.
- extension_count: string The number of extensions added to the property. Between 0 and 4.
- number_habitable_rooms: number Habitable rooms include any living room, sitting room, dining room, bedroom, study and similar; and also a non-separated conservatory. A kitchen/diner having a discrete seating area (with space for a table and four chairs) also counts as a habitable room. A non-separated conservatory adds to the habitable room count if it has an internal quality door between it and the dwelling. Excluded from the room count are any room used solely as a kitchen, utility room, bathroom, cloakroom, en-suite accommodation and similar and any hallway, stairs or landing; and also any room not having a window.
- number_heated_rooms: number The number of heated rooms in the property if more than half of the habitable rooms are not heated.
- low_energy_lighting: number The percentage of low energy lighting present in the property as a percentage of the total fixed lights in the property. 0% indicates that no low-energy lighting is present.
- number_open_fireplaces: number The number of Open Fireplaces in the Property. An Open Fireplace is a fireplace that still allows air to pass between the inside of the Property and the outside.
- hotwater_description: string Overall description of the property feature
- hot_water_energy_eff: string Energy efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- hot_water_env_eff: string Environmental efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- floor_description: string Overall description of the property feature
- windows_description: string Overall description of the property feature
- windows_energy_eff: string Energy efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- windows_env_eff: string Environmental efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- walls_description: string Overall description of the property feature
- walls_energy_eff: string Energy efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- walls_env_eff: string Environmental efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- secondheat_description: string Overall description of the property feature
- roof_description: string Overall description of the property feature
- roof_energy_eff: string Energy efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- roof_env_eff: string Environmental efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- mainheat_description: string Overall description of the property feature
- mainheat_energy_eff: string Energy efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- mainheat_env_eff: string Environmental efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- mainheatcont_description: string Overall description of the property feature
- mainheatc_energy_eff: string Energy efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- mainheatc_env_eff: string Environmental efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- lighting_description: string Overall description of property feature. Total number of fixed lighting outlets and total number of low-energy fixed lighting outlets
- lighting_energy_eff: string Energy efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- lighting_env_eff: string Environmental efficiency rating. One of: very good; good; average; poor; very poor. On actual energy certificate shown as one to five star rating.
- main_fuel: string The type of fuel used to power the central heating e.g. Gas, Electricity
- wind_turbine_count: number Number of wind turbines; 0 if none.
- solar_water_heating_flag: string Indicates whether the heating in the Property is solar powered.
- mechanical_ventilation: string Identifies the type of mechanical ventilation the property has. This is required for the RdSAP calculation.
- address: string Field containing the concatenation of address1, address2 and address3. Note that post code is recorded separately.
- local_authority_label: string The name of the local authority area in which the building is located. This field is for additional information only and should not be relied upon: please refer to the Local Authority ONS Code.
- constituency_label: string The name of the parliamentary constituency in which the building is located. This field is for additional information only and should not be relied upon: please refer to the Constituency ONS Code.
- construction_age_band: string Age band when building part constructed. England & Wales only. One of: before 1900; 1900-1929; 1930-1949; 1950-1966; 1967-1975; 1976-1982; 1983-1990; 1991-1995; 1996-2002; 2003-2006; 2007-2011; 2012 onwards.
- lodgement_datetime: string Date and time lodged on the Energy Performance of Buildings Register.
- tenure: string Describes the tenure type of the property. One of: Owner-occupied; Rented (social); Rented (private).
recommendations: array List of recommendations
- item_text: string Recommendation Text
- indicative_cost number[] Array of Costs

Licensing Schema

current: object Whether the property has currently got a particular licence
- hmo: bool
historic: object Whether the property has ever had a particular licence
- hmo: bool
licences: object[] Licence history for the property
- type: string Licence type, one of mandatory, additional, or selective
- address: string Licence address
- licencee: string Licencee name
- people: int Maximum number of people
- households: int Maximum number of households
- status: string Licence status, one of requested, granted, rejected, or exemption
- date_start: string Licence start date
- date_end: string Licence end date

Property Schema

id: string Kamma Property Id
external_reference: string External reference
address: string Property address
postcode: string Property postcode
council: string The council that the property sits within
council_websites: string[] List of council licensing website links
advice_text: string Advice text that states if a licence is currently required
requires: object
- current: object
  - mandatory: bool[]|null Is the property currently within a mandatory scheme
  - additional: bool[]|null Is the property currently within an additional scheme
  - selective: bool[]|null Is the property currently within a selective scheme
  - article4: bool[]|null Is the property currently within an Article 4
- future: object
  - mandatory: bool[]|null Is the property within a future mandatory scheme
  - additional: bool[]|null Is the property within a future additional scheme
  - selective: bool[]|null Is the property within a future selective scheme
  - article4: bool[]|null Is the property within a future Article 4
approved_scheme: object
- id: int
- type: string One of mandatory, additional, or selective
- date_start: string The date the scheme starts
- date_end: string The date the scheme ends
metadata: object
- people: int Maximum number of people
- households: int Maximum number of households
- storeys: object Maximum number of storeys
  - internal: int Maximum number of internal storeys
  - external: int Maximum number of external storeys
- rooms: int Maximum number of rooms
- above_commercial: int Is the property above commercial premises?. Must be one of 0 or 1.
- property_category: string Property category
- property_class: string Property class
- notes: string Notes about the scheme
analysis: string[] Analysis that should be performed
actions: string[] Advised actions that should be performed
regulations: object[] List of regulations
- id: int
- type: string One of mandatory, additional, or selective
- confidence: number Confidence that the property in inside regulation boundary as a percentage
- date_start: string The date that the regulation starts
- date_end: string The date that the regulation ends
- link: string The URL of the regulation details
- consultation: boolean Is the regulation under consultation
licence_application: object[] Details provided of a client submitted application
- status: string One of requested, granted, rejected, or exemption
- application: object
  - type: string One of mandatory, additional, or selective
  - date_start: string The date the license starts
  - date_end: string The date the license ends
  - max_people: int The maximum number of people the license covers
  - max_households: int The maximum number of households the license covers
  - reference: string The license application reference
planning_application: object[] Details provided of a client submitted application
- status: string One of requested, granted, rejected, or exemption
- application: object
  - type: string The planning application type