openapi: 3.0.0 info: title: Kamma RESTful API version: 1.3.1 description: 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. termsOfService: https://www.kammadata.com/support/terms/ contact: name: Kamma Support email: hello@kammadata.com url: https://www.kammadata.com/support/ externalDocs: description: Read the Getting Started guide url: https://www.kammadata.com/support/api/ servers: - url: https://api.kammadata.com/v1 description: Production server - url: https://api.sandbox.kammadata.com/v1 description: Sandbox server - url: https://api.testing.kammadata.com/v1 description: Testing server - url: https://api.integration.kammadata.com/v1 description: Integration server tags: - name: authentication description: Authentication and authorisation methods - name: property description: Property submission and manangement methods paths: /auth/manager/{managerReference}: post: tags: - "authentication" summary: "Get Manager Privilege" description: "When called with a valid API key and Manager user reference, temporarily elevates the privilege of the API key to that of a manager, allowing API resources to be invoked on all properties for all users that the Manager is responsible for." parameters: - $ref: "#/components/parameters/managerReferenceParam" security: - SecretAuth: [] responses: 200: description: "OK" content: application/json: schema: type: object properties: api_id: $ref: "#/components/schemas/ApiId" success: description: "A flag that denotes success; this will always have a value of `true`" type: boolean token: $ref: "#/components/schemas/ApiKey" example: api_id: 123456 success: true token: "TEST_123" 401: description: "Unauthorised" content: application/json: schema: $ref: "#/components/schemas/ErrorObject" example: api_id: 123456 error: true error_type: authentication /property/view/{propertyId}: post: tags: - "property" summary: "View Property" description: "When called with a valid `propertyId`, this resource returns the current compliance status for the property associated with the `propertyId`." parameters: - $ref: "#/components/parameters/propertyIdParam" security: - TokenAuth: [] responses: 200: description: "OK" content: application/json: schema: $ref: "#/components/schemas/PropertyResponse" example: api_id: 123456 success: true reference: "TEST_123" licence_state: "scanned" licence_type: "mandatory" licence_advice: "Mandatory licensing may be required" council: "Doncaster" council_websites: - "https://www.doncaster.gov.uk/services/housing/houses-in-multiple-occupation-licensing" licences_at_postcode: "yes" licenses_at_address: - 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" licence_application: "requested" planning_application: null 400: description: "Bad Request" content: application/json: schema: $ref: "#/components/schemas/ErrorObject" example: api_id: 123456 error: true error_type: "no_result" error_message: "No result was found for query although at least one row was expected." /property/process: post: tags: - "property" summary: "Register/Update Property" description: "When called with a customer’s `PropertyId`, returns either an initial compliance check for a new property or an updated compliance check for an existing property." security: - TokenAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PropertyRequest" example: property: "TEST_123" address_1: "52 Crown Street" address_2: "London" address_3: "" address_4: "" address_5: "" postcode: "WC1E 6JP" people: 5 households: 5 storeys: 1 storeys_internal: 1 above_commercial: 1 rooms: 3 rent: 360000 category: "licenseable" property_class: "flat" licence_holder: null licence_ref: null licence_type: null licence_date_start: null licence_date_end: null licence_date_frequency: null licence_max_people: null licence_conditions: null licence_application: "requested" planning_application: null owner: null owner_type: null owner_name: null owner_email: null owner_company_number: null responses: 200: description: "OK" content: application/json: schema: $ref: "#/components/schemas/PropertyResponse" example: api_id: 123456 success: true reference: "TEST_123" licence_state: "scanned" licence_type: "mandatory" licence_advice: "Mandatory licensing may be required" council: "Camden" council_websites: - "https://www.camden.gov.uk/houses-multiple-occupation" licences_at_postcode: "yes" licenses_at_address: - 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" licence_application: "requested" planning_application: null 400: description: "Bad Request" content: application/json: schema: $ref: "#/components/schemas/ErrorObject" example: api_id: 123456 error: true error_type: "authentication" error_message: "showLogin" /property/disable: post: tags: - "property" summary: "Disable Property" description: "When called with a customer’s `PropertyId` from a property that has previously been registered, this resource removes the associated property from the Kamma platform and ceases compliance monitoring." security: - TokenAuth: [] requestBody: required: true content: application/json: schema: type: object properties: property: $ref: "#/components/schemas/PropertyId" example: property: "TEST_123" responses: 200: description: "OK" content: application/json: schema: type: object properties: api_id: $ref: "#/components/schemas/ApiId" success: description: "A flag that denotes success; this will always have a value of `true`" type: boolean example: api_id: 123 success: true 400: description: "Bad Request" content: application/json: schema: $ref: "#/components/schemas/ErrorObject" example: api_id: 123456 error: true error_type: "authentication" error_message: "showLogin" /manager/pipeline: post: tags: - "property" summary: "View All Properties" description: "Returns a list of all properties on the Kamma platform associated with the supplied API key. Note that this resource returns a URL which references a JSON file which contains the output of this resource." security: - TokenAuth: [] requestBody: required: true content: application/json: schema: type: object properties: date: $ref: "#/components/schemas/DateTimeStamp" example: date: "2019-06020 16:30:00" responses: 200: description: "OK" content: application/json: schema: type: object properties: api_id: $ref: "#/components/schemas/ApiId" success: description: "A flag that denotes success; this will always have a value of `true`" type: boolean generated: $ref: "#/components/schemas/DateTimeStamp" count: type: integer url: type: string example: api_id: 123456 success: true generated: "2019-06-17 09:08:23" count: 19 url: "https://s3.eu-west-1.amazonaws.com/rentr.store/property_pipelines/property_pipeline_manager_1.json" 400: description: "Bad Request" content: application/json: schema: $ref: "#/components/schemas/ErrorObject" example: api_id: 123456 error: true error_type: "authentication" error_message: "showLogin" components: securitySchemes: SecretAuth: type: apiKey in: query name: secret TokenAuth: type: apiKey in: query name: token parameters: managerReferenceParam: in: path name: managerReference required: true description: "A valid Manager user's reference" schema: type: string propertyIdParam: in: path name: propertyId required: true description: "A unique reference id, supplied during property registration, that identifies a specific property in an API user’s back-end system. This reference id must be unique in the entire database whether you are managing an entire group of brands, a franchise, or a single office" schema: type: string schemas: ApiId: description: "A unique value that identifies a specific invocation of the API and which can be used for subsequent error and debugging investigation" type: integer format: int64 minimum: 1 ApiKey: description: "A valid API key associated with an active Kamma Manager account" type: string Category: description: > This is the category of the property under the Housing Act 2004. In most cases this field can be left as null. If an assessment is made where this information becomes a requirement, we will flag it in a `ValidationObject` * `null` - unknown * `single` - single dwellinghouse * `s254` - Section 254 HMO * `s257` - Section 257 HMO * `licenseable` - Licenseable HMO type: string nullable: true enum: - single - s254 - s257 - licenseable DateTimeStamp: description: "A date and time stamp in the form YYYY-MM-DD HH:MM:SS" type: string nullable: true pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$' DateStamp: description: "A date stamp in the form YYYY-MM-DD" type: string nullable: true pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}$' ErrorObject: type: object properties: api_id: $ref: "#/components/schemas/ApiId" error: type: boolean error_type: $ref: "#/components/schemas/ErrorType" validation_errors: $ref: "#/components/schemas/ValidationObject" ErrorType: description: > Type of error encountered * `validation` - validation error * `authentication` - authentication error * `no_results` - no results found error type: string enum: - validation - authentication - no_result LicenceApplication: description: > Adds information about the state of a licensing application process; this allows the API caller to annotate a property with the state of their application. This value is not supplied by the Kamma platform. * `requested` - more information is needed before being able to make a licence application * `applied` - a licence has been applied for type: string nullable: true enum: - requested - applied LicenceDocumentType: description: > This is the result of the Kamma platform's assessment and each licence * `selective` - the licence was marked as a being selective licensing * `additional` - the licence was marked as a being additional licensing * `mandatory` - the licence was marked as a being mandatory licensing * `unknown` - there is not enough information to make a determination of the licensing type type: string nullable: true enum: - unknown - mandatory - additional - selective LicenceHolder: description: > This is the result of the Kamma platform's assessment and each property will be assigned one of these values * `none` - the property does not require a licence * `agent` - the licence holder is an agent * `owner` - the licence holder is the owner * `third-party` - the licence holder is a third-party * `unknown` - the licence holder is unknown type: string nullable: true enum: - unknown - agent - owner - third-party - none LicenceObject: type: object properties: type: $ref: "#/components/schemas/LicenceDocumentType" address: description: "The address of the property as supplied on this licence" type: string licencee: description: "The name of the individual or organisation that applied for this licence" type: string people: description: "The number of people living in this property" type: integer households: description: "The number of households living in this property" type: integer status: description: "The licence was marked with this status" type: string date_start: description: "Starting date for this licence" $ref: "#/components/schemas/DateStamp" date_end: description: "Ending date for this licence" $ref: "#/components/schemas/DateStamp" LicenceState: description: > This is the result of the Kamma platform's assessment and each property will be assigned one of these values * `scanned` - the property has been added but requires more information to be sure it falls within licensing conditions * `checked` - the property has enough information to make an assessment but has not yet been approved by an authorised user * `approved` an authorised user has confirmed the property's licensing requirements from the Kamma platform's assessment * `complete` - all information required has been given, including the licence document if a licence is required type: string enum: - scanned - checked - approved - complete LicenceType: description: > This is the result of the Kamma platform's assessment and each property will be assigned one of these values * `none` - the property does not require a licence * `selective` - the configuration and location allow us to determine an exact licensing requirement * `additional` - the configuration and location allow us to determine an exact licensing requirement * `mandatory` - the configuration and location allow us to determine an exact licensing requirement * `unknown` - there is not enough information to make a determination and the property falls into two or more licensing types type: string nullable: true enum: - unknown - mandatory - additional - selective - none OwnerId: description: "The Owner’s internal ID on your system which we will keep as the external ID. This ID needs to be unique in the entire database whether you are managing an entire group of brands, a franchise, or a single office" type: string maxLength: 255 OwnerType: description: "The type of property owner such as landlord or agent; this is a free format field" type: string maxLength: 255 PlanningApplication: description: > Adds information about the state of a planning application process; this allows the API caller to annotate a property with the state of their application. This value is not supplied by the Kamma platform. * `applied` - planning permission has been applied for type: string nullable: true enum: - applied PropertyClass: description: > Knowing the type of property will allow us to assess compliance in terms of residential planning permission required across the UK * `null` - information not known * `house` - the property is a detached, semi-detached or terraced house * `flat` - the property is a flat in a purpose-built block of apartments or converted house type: string nullable: true enum: - house - flat PropertyId: description: "A unique reference id, supplied during property registration, that identifies a specific property in an API user’s back-end system. This reference id must be unique in the entire database whether you are managing an entire group of brands, a franchise, or a single office" type: string PropertyRequest: description: > Identifies a property and allow additional information to be associated with the property. Fields marked with an asterisk `*` are mandatory, otherwise they should be assumed to be optional. If a field can accept a null value, it will be annotated with `nullable: true`. type: object required: - property - address_1 - postcode - people - households properties: property: $ref: "#/components/schemas/PropertyId" address_1: description: "Address line 1" type: string address_2: description: "Address line 2" type: string nullable: true address_3: description: "Address line 3" type: string nullable: true address_4: description: "Address line 4" type: string nullable: true address_5: description: "Address line 5" type: string nullable: true postcode: description: "Standard UK postcode; formatted as 6-10 alphanumeric characters" type: string people: description: "Number of people living in the property" type: integer nullable: true households: description: "Number of households living in the property" type: integer nullable: true storeys: description: "Number of external storeys of the building, e.g. a flat above a shop = 2 storeys" type: integer nullable: true storeys_internal: description: "Number of internal storeys in the property, not of the building, e.g. a flat above a shop = 1 storey" type: integer nullable: true rooms: description: "Number of bedrooms in the property" type: integer nullable: true rent: description: "Amount of rent paid, weekly in pence" type: integer nullable: true above_commercial: description: > Is the property above commercial premises? * `0` - no * `1` - yes * `null` - unknown type: integer nullable: true enum: - 0 - 1 category: $ref: "#/components/schemas/Category" property_class: $ref: "#/components/schemas/PropertyClass" licence_holder: $ref: "#/components/schemas/LicenceHolder" licence_ref: description: "Optional; licence reference issued by the Local Authority" type: string nullable: true licence_type: $ref: "#/components/schemas/LicenceType" licence_date_start: $ref: "#/components/schemas/DateStamp" licence_date_end: $ref: "#/components/schemas/DateStamp" licence_date_frequency: description: > How often does the licence renew? * `none` * `yearly` * `monthly` * `quarterly` * `semiannually` type: string enum: - none - yearly - monthly - quarterly - semiannual nullable: true licence_max_people: description: "Both Mandatory and Additional licensing will impose a limit on the number of occupants" type: integer nullable: true licence_conditions: description: "Additional conditions imposed by the Local Authority with the licence" type: string maxLength: 1000 nullable: true licence_application: $ref: "#/components/schemas/LicenceApplication" planning_application: $ref: "#/components/schemas/PlanningApplication" owner: $ref: "#/components/schemas/OwnerId" owner_type: $ref: "#/components/schemas/OwnerType" owner_name: description: "The owner's name" type: string nullable: true owner_email: description: "The owner's email address" type: string format: email nullable: true owner_company_number: description: "The owner's Companies House number, if applicable" type: string nullable: true PropertyResponse: type: object properties: api_id: $ref: "#/components/schemas/ApiId" success: description: "A flag that denotes success; this will always have a value of `true`" type: boolean reference: $ref: "#/components/schemas/PropertyId" licence_state: $ref: "#/components/schemas/LicenceState" licence_type: $ref: "#/components/schemas/LicenceType" licence_advice: type: string council: description: "Name of the local authority, based on the property's postcode" type: string council_websites: description: "List of websites for the `council` relating to licensing" type: array items: type: string licences_at_postcode: description: "Flag denoting whether any licences have been found for this property's postcode" type: boolean licence_at_address: description: > Flag denoting whether a match has been found between the property's postcode and its address * `yes` - a match was found and `licences_at_address` will contain at least one matching licence * `maybe` - an exact match for the property's postcode and address could not be found * `no` - no match for the property's postcode and address could be found and so no licences have been matched type: string enum: - no - maybe - yes licences_at_address: type: array nullable: true items: $ref: "#/components/schemas/LicenceObject" licence_application: $ref: "#/components/schemas/LicenceApplication" planning_application: $ref: "#/components/schemas/PlanningApplication" ValidationObject: description: "An array of validation errors, if `ErrorObject.error_type` contains `validation`" type: array items: description: "Error message" type: string