Published 20th May 2022
The Kamma API provides programmatic access, via a RESTful API, to the Kamma platform and allows you to integrate our platform into your business workflows.
You need a valid Kamma API key to access our API; you can request your API key from the Kamma team.
This page describes v1 of the Kamma API; this is the latest version.
All API resources are accessed from the https://api.kammadata.com/v1 endpoint, which supports SSL access only. Accessing any API resource via vanilla HTTP will result in a Connection refused
error (errno 61).
All call to the Kamma API must be authenticated by a valid API key; this can be specified either as a URL query string parameter for GET
requests or in the request body for POST
requests. Whilst we will continue to support GET
requests for v1 of the API, we strongly recommend protecting the integrity of your API key by using POST
requests.
If an invalid API key is passed or if the API key is missing, an HTTP status of 400 Bad Request
will be returned in the response headers.
Unless explicitly documented in the detailed API documentation, all API request and response bodies must be encoded as UTF-8 JSON. API requests should set the Content-Type
header as follows:
Content-Type: application/json
All our API documentation is generated from our OpenAPI v3.0 Specification. Please see the OpenAPI Initiative website for more information.
You can also download the full Kamma OpenAPI specification for our API.
You can read the full documentation for the API on the Kamma RESTful API v1 page.
The Kamma platform and RESTful API work on the concept of a property, which is uniquely identified and which has metadata which describes the property and which is used to check, determine and monitor the licensing compliance of a property.
Whilst we understand that most property management platforms for the rental market use a workflow which distinguishes between a lease, a tenancy and a property, the Kamma platform only models a property and uses the metadata associated with that property to check the licensing compliance. This is because Property Licensing legislation and compliance is attached to a property (and to a licensee), rather than to a lease.
Once a property has been created in the Kamma platform it is entirely expected that the metadata which describes the property can and will change over time and over multiple tenancies, but as described below, the identifier for a property should not change.
All API methods that require a request body, expect a JSON object comprised of the documented name/value pairs, which are commonly termed JSON properties (not to be confused with the real world, bricks and mortar properties that the API relates to).
Each name/value property is either mandatory or optional.
Any JSON property which is mandatory must be supplied in every request body. If a null
value is permitted for a JSON property, supplying such a value will remove any previously stored value.
Specifying an optional JSON property with a non null
value and that has a value which is valid according to the API documentation:
Specifying an optional JSON property with a null
value, providing this is supported for this property according to the API documentation, will remove this property and any value previously stored.
Alternatively, omitting an optional JSON property from the request body will also remove this property and any value previously stored.
Each property that is registered in the Kamma platform is identified by a unique identifier, the PropertyId
that is required when the property is initially created in the platform or when an existing property is updated or removed from the platform.
It’s important to know that unique refers to the backend platform or workflow that your business uses. Property identifiers are sandboxed to your Kamma account, not to the platform as a whole.
We recommend that you use an identifier that is provided by the property management platform that your business is using, such as a database table primary key or a UUID or GUID. As mentioned above, the basic unit of the Kamma platform is the property. The platform does not model or take into account other concepts that may be associated with a property in your system, such as a lease or a tenancy. It’s critically important that the PropertyId
you use is persistent across all stages of a rental process; if a PropertyId
changes, it will be considered to be a different property by the GetRentr platform.
A property is added to the Kamma platform or an existing property’s metadata is updated with the /property/process
(Register/Update Property) API method. This method has both mandatory metadata parameters and determining metadata parameters as described below.
Determining metadata parameters are those which are needed in order to fully and correctly determine the licensing compliance of a property. It is fully expected that the determining metadata associated with a property will change over time, due to changes in leases or tenancies. The need for some items of this additional metadata is dependent on the property’s location, but provision of all of these fields ensures Kamma’s ability to accurately determine the Property Licensing requirements of all properties.
Mandatory metadata parameters are those which are the minimum needed to register a property within the Kamma platform. It’s important to note that using only the mandatory parameters will not enable the Kamma platform to determine or monitor the licensing compliance of the property.
Thus, the mandatory metadata parameters can be thought of as a placeholder to register the property at an early stage in your business’s workflow and that the metadata for the property will be updated with the full set of determining metadata parameters during the course of your workflow. Once the full set of determining metadata parameters are updated for a given property, the Kamma platform will be able to report on the licensing compliance for that property and then monitor for compliance changes, based on both external factors, such as licensing scheme durations as well as internal factors, such as amending and updating the property metadata.
The mandatory metadata parameters for a property are:
The determining metadata parameters for a property are:
The current licensing compliance for a property, based on the metadata that has been supplied when the property was initially created in the platform or last updated is provided by the /property/view/{propertyId}
(View Property) API method.
If a property is no longer required to be registered or monitored by the Kamma platform, it can be removed by the /property/disable
(Disable Property) API method.
Book a demo or get in touch
If you'd like to see the power of the Kamma platform in action, you can book a demo with us by simply clicking on the Book a Demo link at the top of the page.
Otherwise, email us at hello@kammadata.com or let us know your contact details using this form and we will get back to you as soon as we can.
Sending message...
Sorry, but something went wrong. Please let us know and we'll do our best to fix it.
Hi
Thanks for sending us your message. You'll be hearing from us shortly.