MENU navbar-image

Introduction

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

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.

$ 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

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

Headers

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:

Content-Type: application/json
Accept: 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.

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

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

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

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

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 and looks like geoplace:uprn:100023433011.

Address

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, such as kamma:address:thanet+house+231+strand+london+wc2r+1da.

Base URL

https://kamma.api.kammadata.com

Authenticating requests

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.

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

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();
$response = $client->get(
    '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',
        ],
    ]
);
$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"
}

Request   

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

URL Parameters

identifier  string  

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

Response

Response Fields

response_id  string  

The unique id of API request

result  object  

The EPC object. For full description see EPC Schema.

result.certificate  object  

Data from the EPC

result.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();
$response = $client->get(
    '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',
        ],
    ]
);
$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"
}

Request   

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

URL Parameters

identifier  string  

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

Response

Response Fields

response_id  string  

The unique id of this API request

result  object  

Licensing determination result. For full description see Determination Schema.

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

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

result.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();
$response = $client->get(
    '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',
        ],
    ]
);
$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"
}

Request   

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

URL Parameters

identifier  string  

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

Response

Response Fields

response_id  string  

The unique id of api request

result  object  

The licensing object. For full description see Licensing Schema.

result.current  object  

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

result.historic  object  

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

result.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();
$response = $client->get(
    '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',
        ],
    ]
);
$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"
}

Request   

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

URL Parameters

identifier  string  

A Kamma Property Id.

Response

Response Fields

response_id  string  

The unique id of api request

result  object  

The success state. For full description see Identifier Schema.

result.id  string  

The property unique identifier

result.external_reference  string  

The external property reference

result.address  string  

The property address

result.postcode  string  

The property postcode

result.council  string  

The council that the property sits within

result.council_websites  string[]  

List of council licensing website links

result.active_text_current  string  

Advice text that states if a licence is currently required

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

result.requires  object  

Current and future requirements

result.approved_scheme  object  

Approved scheme details

result.metadata  object  

Additional information about property

result.analysis  string[]  

Advice on the type of analysis that should be performed

result.actions  string[]  

Advice on the actions that should be performed

result.regulations  object[]  

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

result.licence_application  object  

Licence application

result.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\": \"s254\",
    \"property_class\": \"flat\",
    \"notes\": \"\",
    \"licence_status\": \"requested\",
    \"licence_type\": \"additional\",
    \"licence_date_start\": \"2020-01-25\",
    \"licence_date_end\": \"2025-01-25\",
    \"licence_max_people\": 5,
    \"licence_max_households\": 5,
    \"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": "s254",
    "property_class": "flat",
    "notes": "",
    "licence_status": "requested",
    "licence_type": "additional",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 5,
    "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();
$response = $client->post(
    'https://kamma.api.kammadata.com/api/properties/create',
    [
        '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' => 's254',
            'property_class' => 'flat',
            'notes' => '',
            'licence_status' => 'requested',
            'licence_type' => 'additional',
            'licence_date_start' => '2020-01-25',
            'licence_date_end' => '2025-01-25',
            'licence_max_people' => 5,
            'licence_max_households' => 5,
            '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": "s254",
    "property_class": "flat",
    "notes": "",
    "licence_status": "requested",
    "licence_type": "additional",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 5,
    "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 (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"
}

Request   

POST api/properties/create

Body Parameters

address  string  

A full street level address or UPRN.

postcode  string  

The property’s postcode.

external_reference  string optional  

Your own external reference.

people  integer optional  

Number of people living in the property.

households  integer optional  

Number of households living in the property.

storeys_internal  integer optional  

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

storeys_external  integer optional  

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

above_commercial  integer optional  

Is the property above commercial premises?. Must be one of 0 or 1.

rooms  integer optional  

Number of bedrooms in the property.

rent  integer optional  

Amount of rent paid, weekly in pence.

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. Must be one of single, s254, s257, or 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. Must be one of house or flat.

notes  string optional  

licence_status  string optional  

Must be one of applied, inprogress, or requested.

licence_type  string optional  

This is the result of the Kamma platform's assessment. Must be one of unknown, mandatory, additional, selective, or none.

licence_date_start  string optional  

Licence start date. Must be a valid date in the format Y-m-d.

licence_date_end  string optional  

Licence end date. Must be a valid date in the format Y-m-d.

licence_max_people  integer optional  

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

licence_max_households  integer optional  

licence_reference  string optional  

Optional; licence reference issued by the Local Authority.

planning_status  string optional  

Must be one of applied, inprogress, or requested.

planning_reference  string optional  

Response

Response Fields

response_id  string  

The unique id of api request

result  object  

The success state. For full description see Identifier Schema.

result.id  string  

The Kamma Property Id

result.external_reference  string  

The external property reference

result.address  string  

The property address

result.postcode  string  

The property postcode

result.council  string  

The council that the property sits within

result.council_websites  string[]  

List of council licensing website links

result.active_text  string  

Advice text that states if a licence is currently required

result.requires  object  

Current and future requirements

result.approved_scheme  object  

Approved scheme details

result.metadata  object  

Additional information about property

result.analysis  string[]  

Advice on the type of analysis that should be performed

result.actions  string[]  

Advice on the actions that should be performed

result.regulations  object[]  

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

result.licence_application  object  

Licence application

result.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\": \"s254\",
    \"property_class\": \"flat\",
    \"notes\": \"\",
    \"licence_status\": \"applied\",
    \"licence_type\": \"none\",
    \"licence_date_start\": \"2020-01-25\",
    \"licence_date_end\": \"2025-01-25\",
    \"licence_max_people\": 5,
    \"licence_max_households\": 12,
    \"licence_reference\": \"ref-12345\",
    \"planning_status\": \"requested\",
    \"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": "s254",
    "property_class": "flat",
    "notes": "",
    "licence_status": "applied",
    "licence_type": "none",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 12,
    "licence_reference": "ref-12345",
    "planning_status": "requested",
    "planning_reference": "ref-12345"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://kamma.api.kammadata.com/api/properties/sync/kamma:property:d293bfc0e2fc69b2a411ecc1dcdff3e0',
    [
        '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' => 's254',
            'property_class' => 'flat',
            'notes' => '',
            'licence_status' => 'applied',
            'licence_type' => 'none',
            'licence_date_start' => '2020-01-25',
            'licence_date_end' => '2025-01-25',
            'licence_max_people' => 5,
            'licence_max_households' => 12,
            'licence_reference' => 'ref-12345',
            'planning_status' => 'requested',
            '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": "s254",
    "property_class": "flat",
    "notes": "",
    "licence_status": "applied",
    "licence_type": "none",
    "licence_date_start": "2020-01-25",
    "licence_date_end": "2025-01-25",
    "licence_max_people": 5,
    "licence_max_households": 12,
    "licence_reference": "ref-12345",
    "planning_status": "requested",
    "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 (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"
}

Request   

PUT api/properties/sync/{identifier}

URL Parameters

identifier  string  

A Kamma Property Id.

Body Parameters

address  string  

A full street level address or UPRN.

postcode  string  

The property’s postcode.

external_reference  string optional  

Your own external reference.

people  integer optional  

Number of people living in the property.

households  integer optional  

Number of households living in the property.

storeys_internal  integer optional  

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

storeys_external  integer optional  

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

above_commercial  integer optional  

Is the property above commercial premises?. Must be one of 0 or 1.

rooms  integer optional  

Number of bedrooms in the property.

rent  integer optional  

Amount of rent paid, weekly in pence.

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. Must be one of single, s254, s257, or 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. Must be one of house or flat.

notes  string optional  

licence_status  string optional  

Must be one of applied, inprogress, or requested.

licence_type  string optional  

This is the result of the Kamma platform's assessment. Must be one of unknown, mandatory, additional, selective, or none.

licence_date_start  string optional  

Licence start date. Must be a valid date in the format Y-m-d.

licence_date_end  string optional  

Licence end date. Must be a valid date in the format Y-m-d.

licence_max_people  integer optional  

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

licence_max_households  integer optional  

licence_reference  string optional  

Optional; licence reference issued by the Local Authority.

planning_status  string optional  

Must be one of applied, inprogress, or requested.

planning_reference  string optional  

Response

Response Fields

response_id  string  

The unique id of api request

result  object  

The success state. For full description see Identifier Schema.

result.id  string  

The property unique identifier

result.external_reference  string  

The external property reference

result.address  string  

The property address

result.postcode  string  

The property postcode

result.council  string  

The property council

result.council_websites  string[]  

List of council websites

result.active_text  string  

Advice text

result.requires  object  

Current and future requirements

result.approved_scheme  object  

Approved scheme details

result.metadata  object  

Additional information about property

result.analysis  string[]  

Advice on the type of analysis that should be performed

result.actions  string[]  

Advice on the actions that should be performed

result.regulations  object[]  

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

result.licence_application  object  

Licence application

result.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();
$response = $client->delete(
    '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',
        ],
    ]
);
$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 (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"
}

Request   

DELETE api/properties/archive/{identifier}

URL Parameters

identifier  string  

A Kamma Property Id.

Response

Response Fields

response_id  string  

The unique id of api request

result  object  

The success state

result.id  string  

The property unique identifier

result.success  boolean  

Success state of the archive request

Schemas

Determination Schema

EPC Schema

Licensing Schema

Property Schema