InventoryBase API

Welcome to InventoryBase! This page provides full documentation for the InventoryBase API.

Note that we may, without notice, add additional fields to API responses. These are not considered breaking changes. Just be sure your integration doesn't blow up when we add additional fields!

Our API supports both JSON and XML. We strongly encourage you to use JSON.

JSON

Example JSON

{
    "foo": "bar",
    "hello": ["Dan", "Bob"],
    "world_ended": false,
    "pi": 3.14,
    "address": {
        "line1": "9 Long Street",
        "city": "Portsmouth",
        "postcode": "PO1 1AB"
    }
}

To receive a response formatted as JSON, use the header: Accept: application/json.

If you're providing data in your request as JSON, use the header: Content-Type: application/json.

Note JSON is the default, and will be used in the absence of, or invalid, headers.

XML

Example XML using JSONx

<?xml version="1.0" encoding="UTF-8"?>
<json:object xmlns:json="http://www.ibm.com/xmlns/prod/2009/jsonx" xsi:schemaLocation="http://www.datapower.com/schemas/json jsonx.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <json:string name="foo">bar</json:string>
 <json:array name="hello">
  <json:string>Dan</json:string>
  <json:string>Bob</json:string>
 </json:array>
 <json:boolean name="world_ended">false</json:boolean>
 <json:number name="pi">3.14</json:number>
 <json:object name="address">
  <json:string name="line1">9 Long Street</json:string>
  <json:string name="city">Portsmouth</json:string>
 </json:object>
</json:object>

While our API is primarily JSON, we do offer XML support through automatic request & response conversion. We do this using IBM's standard for encoding JSON as XML, JSONx.

To receive a response formatted as XML, use the header: Accept: application/xml.

If you're providing data in your request as XML, use the header: Content-Type: application/xml.

Remember that if you leave out these headers, your request will be interpreted as JSON, and you'll receive an error in response (itself formatted in JSON).

Authentication

For authentication with the API, we use OAuth Access Tokens. To get started, you'll need to register your Application with us.

NOTE: first, you'll need to have an InventoryBase account. Sign up here. You do not need to pay for your account if you're only creating applications (sign up for your free trial and just let it expire).

Create your Application (OAuth Client)

Now, go to here and enter a name for your application, e.g. Foo Lettings Software. On the next page you can enter details about your application which we'll show the user.

Next, enter a Redirect URL which we'll send the user back to with their code (step 2 of the "OAuth Flow" section below).

Finally, note down your Client ID and Client Secret tokens.

Allowed Scopes

Scope Description
profile.read Read Basic profile details
properties.read List Properties
properties.write Manage Properties
inspections.read List Inspections
inspections.write Manage Inspections
reports.read Read Inspection reports
reports.write Modify Inspection reports
clients.read List Clients
clients.write Manage Clients
staff.read List Staff users
staff.write Manage Staff users
templates.read List Templates
templates.write Manage Templates
webhooks.read List Registered webhooks
webhooks.write Manage Webhooks
file-share.read List file shares
file-share.write Manage file shares
configuration.read List configurations

Each API endpoint below will have one or several of the above scopes listed next to it.

Your application must have requested all of the listed scopes to access that endpoint.

OAuth Flow

The InventoryBase API adheres to the OAuth 2 specification, exposing only the "Authorization Code" grant. We further implement a further draft extension of the spec in order to provide XML support on these requests.

Please note that the format of requests, responses and errors are different on the OAuth endpoints in both JSON and XML. This is to adhere with the OAuth 2 spec. If you're using XML, please note that the OAuth responses are not in the JSONx format.

1. Redirect user to request integration

Redirect to OAuth Authorization

https://my.inventorybase.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URL
  &scope=SCOPES_YOU_WANT_SPACE_SEPARATED
  &state=AN_OPTIONAL_NONCE

In your application you may have a "Connect with InventoryBase" button. This should redirect the user to the OAuth Authorization URL.

Parameters

Field Description
response_type Required Must be code
client_id Required The Client ID of your InventoryBase application
redirect_uri Required The URL in your app where the user will be sent back to. Must be in your previously approved list
scope Required A space-separated list of scopes (permissions) you would like to request from the user
state An unguessable random string. It can be used to protect against cross-site request forgery attacks

The user will now login to their InventoryBase account (if they're not already signed in) and we'll present them with a page confirming they want to give your application access to do certain actions on their behalf.

2. InventoryBase redirects back to your site

Incoming Request

GET https://your-site.com/redirect-path?code=XXX&state=YYY

Assuming the user approves your request for integration, we will redirect back to your site with a temporary code in the code parameter and the state you provided us. If the state does not match what you expect, abort the request.

3. Exchange the code for an Access Token

Send the code parameter acquired from the redirect in the previous step back to InventoryBase along with your application details to receive a permanent Access Token for the user.

Your request MUST be a POST request.

Your request MUST be sent encoded as x-www-form-urlencoded.

Your request MAY specify a response format using the Accept header as application/json or application/xml. If you don't supply one, the response will be supplied as application/json.

Request Access Token

POST /oauth/token HTTP/1.1
Host: https://my.inventorybase.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=XXX&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=YOUR_SITE

Parameters

Field Description
grant_type Required Must be authorization_code
code Required The code parameter you just received
client_id Required The Client ID of your InventoryBase application
client_secret Required The Client Secret of your InventoryBase application
redirect_uri Required The URL in your app where the user was previously redirected to. This must match the field provided in the first request

JSON Response

{
    "token_type": "Bearer",
    "expires_in": 7200,
    "access_token": "THE_ACCESS_TOKEN",
    "refresh_token": "THE_REFRESH_TOKEN"
}

XML Response

<oauth>
  <token_type>Bearer</token_type>
  <expires_in>7200</expires_in>
  <access_token>THE_ACCESS_TOKEN</access_token>
  <refresh_token>THE_REFRESH_TOKEN</refresh_token>
</oauth>

Response

Field Description
token_type Will always be Bearer
expires_in Seconds until the access token expires
access_token The access token
refresh_token The refresh token

Refreshing access tokens

Access tokens by default will expire after 2 hours, you can use the refresh token to get a new access token. Refresh tokens are long lived but may only be used once, you will be issued a new refresh token when requesting a new access token.

Your request MUST be a POST request.

Your request MUST be sent encoded as x-www-form-urlencoded.

Your request MAY specify a response format using the Accept header as application/json or application/xml. If you don't supply one, the response will be supplied as application/json.

Refresh Access Token

POST /oauth/token HTTP/1.1
Host: https://my.inventorybase.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=THE_REFRESH_TOKEN_HERE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=SCOPES_YOU_WANT_SPACE_SEPARATED

Parameters

Field Description
grant_type Required Must be refresh_token
refresh_token Required The refresh token you were last issued
client_id Required The Client ID of your InventoryBase application
client_secret Required The Client Secret of your InventoryBase application
scope A space-separated list of scopes (permissions) you would like to request. You cannot request more scopes than your previous token has

JSON Response

{
    "token_type": "Bearer",
    "expires_in": 7200,
    "access_token": "THE_NEW_ACCESS_TOKEN",
    "refresh_token": "THE_NEW_REFRESH_TOKEN"
}

XML Response

<oauth>
  <token_type>Bearer</token_type>
  <expires_in>7200</expires_in>
  <access_token>THE_NEW_ACCESS_TOKEN</access_token>
  <refresh_token>THE_NEW_REFRESH_TOKEN</refresh_token>
</oauth>

Response

Field Description
token_type Will always be Bearer
expires_in Seconds until the access token expires
access_token The new access token
refresh_token The new refresh token

Making Authenticated API Requests

You can now make API calls on their user's behalf by including an Authorization header field on requests:

Authenticated API Request
GET /me HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer THE_ACCESS_TOKEN_HERE

JSON Response

{
    "id": 1,
    "name": "Joe Bloggs",
    "email": "joe.bloggs@example.com",
    "company": "ACME Inc",
    "role": 2
}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<json:object xmlns:json="http://www.ibm.com/xmlns/prod/2009/jsonx" xsi:schemaLocation="http://www.datapower.com/schemas/json jsonx.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <json:number name="id">1</json:number>
    <json:string name="name">Joe Bloggs</json:string>
    <json:string name="email">joe.bloggs@example.com</json:string>
    <json:string name="company">ACME Inc</json:string>
    <json:number name="role">2</json:number>
</json:object>

Properties

InventoryBase stores your properties in the system to assign reports to. Each property will store all reports and maintain its own audit trail for the lifetime of the property.

If you wish to use the API to create Inspections, you will first need to create the Property, unless passing an existing property's ID.

The Property object

{
    "id": 1,
    "ref": "DEMO00001",
    "address": {
        "line1": "100 Example Street",
        "line2": null,
        "city": "Portsmouth",
        "county": "Hampshire",
        "postcode": "PO3 6FY",
        "country": "United Kingdom"
    },
    "geocoords": {
        "lat": "50.8148511",
        "lng": "-1.0965217"
    },
    "furnished": "Unfurnished",
    "type": "House",
    "detachment": "Semi-detached",
    "no_of_beds": 4,
    "no_of_baths": 2,
    "no_of_garages": 1,
    "parking": false,
    "garden": true,
    "notes": "Some notes",
    "uprn": "12345678",
    "client": {
        "id": 4,
        "name": "Ali Smith"
    },
    "tags": ["Tag 1", "Tag 2", "Tag 3"],
    "customFields": {
        "1": {
            "name": "Region",
            "value": "South West",
            "required": false
        }
    }
}
Field Type Description
id int Unique identifier for the object
ref string / null A user-defined reference for the Property - no integrity is enforced.
address object
line1 string Address Line 1 (e.g. the house number & street)
line2 string / null Address Line 2
city string
county string
postcode string
country string
geocoords object
lat string / null The Latitude of the Property, if known
lng string / null The Longitude of the Property, if known
furnished string One of "Unfurnished", "Part Furnished", "Fully Furnished"
type string Type of property this is, e.g. "House", "Apartment", "Castle" etc.
detachment string / null May be one of "Detached", "Semi-Detached", "Mid Terrace", "End Terrace"
no_of_beds int Number of Bedrooms
no_of_baths int Number of Bathrooms
no_of_garages int Number of Garages
parking bool Whether the Property has parking or not
garden bool Whether the Property has garden or not
client object / null The Client the Property belongs to
id int Client identifier
name string Client's full name
tags string[] Tags for the property
uprn string The UPRN (unique property reference number) for the property
customFields object Custom field values for the property
[customFieldId] int An object that maps the ID of the custom field to the value. When updating an inspection, you must provide all other values of custom fields.
value string The value for the custom field ID
name string The name of the custom field
required boolean If the custom field value is required

List all properties

Request
GET /properties HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "pagination": {
        "perPage": 30,
        "currentPage": 1,
        "totalPages": 1,
        "totalRecords": 3
    },
    "links": {
        "first": "https://api.inventorybase.com/properties/?page=1",
        "prev": null,
        "self": "https://api.inventorybase.com/properties/?page=1",
        "next": null,
        "last": "https://api.inventorybase.com/properties/?page=1"
    },
    "data": [
        {
            "id": 1,
            "ref": "DEMO00001",
            "address": {
                "line1": "100 Example Street",
                "line2": null,
                "city": "Portsmouth",
                "county": "Hampshire",
                "postcode": "PO3 6FY",
                "country": "United Kingdom"
            },
            "geocoords": {
                "lat": "50.8148511",
                "lng": "-1.0965217"
            },
            "furnished": "Unfurnished",
            "type": "House",
            "detachment": "Semi-detached",
            "no_of_beds": 4,
            "no_of_baths": 2,
            "no_of_garages": 1,
            "parking": false,
            "garden": true,
            "notes": "Some notes",
            "uprn": "12345678",
            "client": {
                "id": 4,
                "name": "Ali Smith"
            },
            "customFields": {
                "1": {
                    "name": "Region",
                    "value": "South West",
                    "required": false
                }
            }
        }
    ]
}

Retrieve a paginated list of all the user's properties, sorted by creation date - most recent first.

Query Parameters

Field Type Description
per_page int Specify the page number
client_id int Find for a specific client
address string Perform a full-address search

Get a single property

Request
GET /properties/1 HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "id": 1,
    "ref": "DEMO00001",
    "address": {
        "line1": "100 Example Street",
        "line2": null,
        "city": "Portsmouth",
        "county": "Hampshire",
        "postcode": "PO3 6FY",
        "country": "United Kingdom"
    },
    "geocoords": {
        "lat": "50.8148511",
        "lng": "-1.0965217"
    },
    "furnished": "Unfurnished",
    "type": "House",
    "detachment": "Semi-detached",
    "no_of_beds": 4,
    "no_of_baths": 2,
    "no_of_garages": 1,
    "parking": false,
    "garden": true,
    "notes": "Some notes",
    "client": {
        "id": 4,
        "name": "Ali Smith"
    },
    "uprn": "12345678",
    "customFields": {
        "1": {
            "name": "Region",
            "value": "South West",
            "required": false
        }
    }
}

Retrieve a single property by it's id.

Creating a Property

Request

POST /properties HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "address": {
    "line1": "1 Brecon House",
    "city": "Portsmouth",
    "postcode": "PO1 3BP"
  },
  "ref": "OFJFI2922",
  "furnished": "Unfurnished",
  "type": "Apartment",
  "no_of_beds": 1,
  "no_of_baths": 1,
  "notes": "Foo bar baz quz",
  "uprn": "12345678",
  "tags": ["Tag 1", "Tag 2", "Tag 3"],
  "custom_fields": {
    "123": { value: '1996' },
    "456": { value: 'Back Garden Access' },
  },
}

Response

{
  "id": 3,
  "ref": "OFJFI2922",
  "address": {
    "line1": "9 Long Street",
    "line2": null,
    "city": "Portsmouth",
    "county": null,
    "postcode": "PO1 3BP",
    "country": "United Kingdom"
  },
  "geocoords": {
    "lat": "50.794844",
    "lng": "-1.104757"
  },
  "furnished": "Unfurnished",
  "type": "Apartment",
  "detachment": null,
  "no_of_beds": 1,
  "no_of_baths": 1,
  "no_of_garages": null,
  "parking": false,
  "garden": false,
  "notes": "Foo bar baz qux",
  "client": null,
  "uprn": "12345678",
  "tags": ["Tag 1", "Tag 2", "Tag 3"],
  "customFields": {
    "123": { "name": "Year Built", "required": false, "value": '1996' },
    "456": {  "name": "Misc", "required": false, "value": 'Back Garden Access' },
  }
}

Perform a POST request to the /properties endpoint.

Input

Field Type Description
address object
line1 string Required
line2 string?
city string Required
county string?
postcode string Required
ref string?
client object
id int? The ID of the Client to associate the Property with
furnished string?
type string?
detachment string?
no_of_beds int Required
no_of_baths int Required
no_of_garages int?
parking bool
garden bool
notes string?
uprn string?
tags string[]
custom_fields object Value of the custom field
id int The ID of the custom field
value string The value of the custom field

NB: Custom fields must be enabled on your account to use them. To get all available custom fields for properties, send a GET request to /custom-fields/properties

Update a Property

Request

PUT /properties/3 HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "furnished": "Fully Furnished",
  "type": "Apartment",
  "no_of_beds": 3,
  "no_of_baths": 2,
  "uprn": "12345678",
  "tags": ["Tag 1", "Tag 2", "Tag 3", "New Tag"],
  "custom_fields": {
    "1": "1996"
  }
}

Response

{
  "id": 3,
  "ref": "OFJFI2922",
  "address": {
    "line1": "9 Long Street",
    "line2": null,
    "city": "Portsmouth",
    "county": null,
    "postcode": "PO1 3BP",
    "country": "United Kingdom"
  },
  "geocoords": {
    "lat": "50.794844",
    "lng": "-1.104757"
  },
  "furnished": "Fully Furnished",
  "type": "Apartment",
  "detachment": null,
  "no_of_beds": 3,
  "no_of_baths": 2,
  "no_of_garages": null,
  "parking": false,
  "garden": false,
  "notes": "Foo bar baz qux",
  "uprn": "12345678",
  "client": null,
  "tags": ["Tag 1", "Tag 2", "Tag 3", "New Tag"],
  "customFields": {
    "1": {
      "name": "Year built",
      "value": "1996",
      "required": false
    }
  }
}

Perform a PUT request to the /properties/{propertyId} endpoint.

Input should contain the fields which need to be updated.

Property Meters

InventoryBase can store your meter readings for each property, allowing you to easily track the latest/previous reading for meters within the property.

The Meter object

{
    "id": 1,
    "type": "Gas",
    "location": "Under the Stairs",
    "supplier": "British Gas",
    "reading": "7100",
    "date": "2024-03-15T12:30:00+00:00",
    "serial_no": null,
    "attachments": [],
    "parent_id": null
}

List all meters

Request
GET /properties/1/meters HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Query Parameters

Field Type Description
embed string Providing previous_readings will embed all previous readings for the meter
Response
[
    {
        "id": 1,
        "type": "Gas",
        "location": "Under the Stairs",
        "supplier": "British Gas",
        "reading": "7100",
        "date": "2024-03-15T12:30:00+00:00",
        "serial_no": null,
        "attachments": [],
        "parent_id": null
    }
]

Get a single meter

Request
GET /properties/1/meters/2 HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "id": 2,
    "type": "Gas",
    "location": "Under the Stairs",
    "supplier": "British Gas",
    "reading": "7100",
    "date": "2024-03-15T12:30:00+00:00",
    "serial_no": null,
    "attachments": [],
    "parent_id": null
}

Create a meter

Request
POST /properties/1/meters HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "type": "Gas",
    "location": "Under the Stairs",
    "supplier": "British Gas",
    "reading": "7400",
    "date": "2024-03-20T14:15:00+00:00",
    "serial_no": "123456789",
    "parent_id": null
}
Response
{
    "id": 1,
    "type": "Gas",
    "location": "Under the Stairs",
    "supplier": "British Gas",
    "reading": "7400",
    "date": "2024-03-20T14:15:00+00:00",
    "serial_no": "123456789",
    "attachments": [],
    "parent_id": null
}

Update a meter

Request
PUT /properties/1/meters/2 HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "id": 2,
    "type": "Gas",
    "location": "Under the Stairs",
    "supplier": "British Gas",
    "reading": "7400",
    "date": "2024-03-20T14:15:00+00:00",
    "serial_no": "123456789",
    "attachments": [],
    "parent_id": null
}
Response
{
    "id": 1,
    "type": "Gas",
    "location": "Under the Stairs",
    "supplier": "British Gas",
    "reading": "7400",
    "date": "2024-03-20T14:15:00+00:00",
    "serial_no": "123456789",
    "attachments": [],
    "parent_id": null
}

Delete a meter

Request
DELETE /properties/1/meters/2 HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response

200 Status Code

Inspections

Create or retrieve inspection appointments to conduct some type of property report. If you're creating an inspection for a new Property, you will need to create the property first, or you can pass an existing property's ID.

Inspections will be created as Pending, by default, unless you pass a Clerk ID, in which case they will be Assigned. You can query the Staff endpoint to find a clerk's ID.

Inspection States

Code Name Description
100 "Pending" Inspection appointment added
200 "Assigned" Inspection assigned to staff member
300 "Active" Inspection active/in progress
310 "Processing" Inspection awaiting transcription
350 "Review" Inspection in management review
400 "Complete" Inspection completed and report ready
500 "Closed" Inspection closed and archived

Inspection Types

Code Name Description
1 "Inventory" Standard Inventory & Schedule of Condition
2 "Check In" / "Move In" Start-of-Tenancy Report
3 "Inspection" Standalone Inspection from Template
4 "Update" Amendment to standard Inventory
5 "Check Out" / "Move Out" End-of-Tenancy Comparison
6 "Inventory & Check In" / "Inventory & Move In" Combined Inventory & Start-of-Tenancy
7 "Risk Assessment" Standalone Risk Assessment from Template
8 "Routine Inspection" Continued from previous report

The Inspection object

{
    "id": 1,
    "account_id": 1,
    "actor_id": 1,
    "property": {
        "id": 1,
        "ref": "DEMO00001",
        "address": {
            "line1": "100 Example Street",
            "line2": null,
            "city": "Portsmouth",
            "county": "Hampshire",
            "postcode": "PO3 6FY",
            "country": "United Kingdom"
        },
        "geocoords": {
            "lat": "50.8148511",
            "lng": "-1.0965217"
        },
        "furnished": "Unfurnished",
        "type": "House",
        "detachment": "Semi-detached",
        "no_of_beds": 4,
        "no_of_baths": 2,
        "no_of_garages": 1,
        "parking": false,
        "garden": true,
        "notes": "Some notes",
        "client": {
            "id": 4,
            "name": "Ali Smith"
        }
    },
    "clerk": {
        "id": 14,
        "name": "Dan Harper",
        "is_manager": true
    },
    "typist": {
        "id": 192,
        "name": "Bob Jones",
        "is_manager": false
    },
    "state": {
        "id": 350,
        "name": "Review"
    },
    "type": {
        "id": 1,
        "name": "Inventory"
    },
    "ref": "JD192",
    "title": "Inventory & Schedule of Condition",
    "client_id": 4,
    "report_key": "543fe90d312b3",
    "location_of_keys": "With Agent",
    "return_key": "Return to agent",
    "cover_image": {
        "id": 2,
        "url": "http://path/to/image.jpg"
    },
    "notes": {
        "report": null,
        "internal": null,
        "client": "Thanks :)"
    },
    "conduct_date": "2014-10-17T05:30:00",
    "conduct_date_option": 0,
    "start_date": "2014-10-17T05:25:00",
    "started_at": "2014-10-17T05:25:00",
    "submitted_at": "2014-10-17T06:36:02",
    "updated_at": "2014-10-17T06:36:02",
    "reopened_from_review_at": null,
    "completed_at": null,
    "closed_at": null,
  "customFields": {
    "1": {
      "name": "Test field",
      "value: "test",
      "required": false,
    }
  }
}
Field Type Description
id int Unique identifier for the object
account_id int Unique identifier for the account
actor_id int | null Unique identifier for the person who created the Inspection
property

Property

 The Property the Inspection is for
clerk object | null The Clerk assigned to this Inspection
id int Unique identifier for the User/Clerk
name string The Clerk's full name
is_manager bool Is the Clerk part of Management (has more priviledges)
typist object | null The Typist assigned to this Inspection
id int Unique identifier for the User/Typist
name string The Typist's full name
is_manager bool Is the Typist part of Management (has more priviledges)
state object
id int Numerical representation of the state
name string Textual representation of the state

The possible Inspection states are detailed above.

type object
id int Numerical representation of the inspection type
name string Textual representation of the inspection type

The possible Inspection types are detailed above.

ref string | null A user-defined reference for the Inspection - no integrity is enforced
title string A customisable report title
client_id int | null Identifier of the Client the Inspection is carried out on behalf of
report_key string A random unique key used for accessing the completed report
location_of_keys string Where the Clerk can find the keys to the Property
return_key string | null Where the key should be returned to
cover_image object | null
id int Numerical representation of the Cover Image attachment
url string The URL of the Cover Image
notes object
report string | null Notes which will be displayed on the Notes page of the generated report
internal string | null Notes shared only interally with staff, not seen by the Client
client string | null Notes shared with the Client
pricing object | null
price string idk?
additional string idk?
margin string idk?
time_to_complete iso 8601 duration | null An ISO 8601 duration string representing the expected time it will take the inspection to be completed in; e.g. PT1H30M represents 1 hour and 30 minutes. Must be at least 1 minute long.
conduct_date iso 8601 | null Date the Inspection is scheduled to be carried out on
conduct_date_option 0|1 If the inspection is confirmed (0) or not (1)
start_date iso 8601 | null Date the Inspection was marked Active DEPRECATED use started_at instead.
started_at iso 8601 | null Date the Inspection was marked Active
submitted_at iso 8601 | null Date the Inspection was submitted for Review
updated_at iso 8601 | null Date the Inspection was last updated
completed_at iso 8601 | null Date the Inspection was marked Complete
closed_at iso 8601 | null Date the Inspection was Closed
reopened_from_review_at iso 8601 | null Date the Inspection was reopened from review
customFields object Custom field values for the inspection
[customFieldId] object An object that maps the ID of the custom field to the value. When updating an inspection, you must provide all other values of custom fields.
value string The value for the custom field ID
name string The name of the custom field
required boolean If the custom field value is required

The Report object

{
    "rooms": [],
    "pending_attachments": {}
}
Field Type Description
rooms Room[] An array of Room objects
pending_attachments object Keys: the provided UUID from the uploading application; Values: a delivery key for the attachment associated with the UUID

Get an inspection

Request
GET /inspections/{inspectionId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "id": 1,
    "account_id": 1,
    "property": {
        "id": 1,
        "ref": "DEMO00001",
        "address": {
            "line1": "100 Example Street",
            "line2": null,
            "city": "Portsmouth",
            "county": "Hampshire",
            "postcode": "PO3 6FY",
            "country": "United Kingdom"
        },
        "geocoords": {
            "lat": "50.8148511",
            "lng": "-1.0965217"
        },
        "furnished": "Unfurnished",
        "type": "House",
        "detachment": "Semi-detached",
        "no_of_beds": 4,
        "no_of_baths": 2,
        "no_of_garages": 1,
        "parking": false,
        "garden": true,
        "notes": "Some notes",
        "client": {
            "id": 4,
            "name": "Ali Smith"
        }
    },
    "clerk": {
        "id": 14,
        "name": "Dan Harper",
        "is_manager": true
    },
    "typist": {
        "id": 192,
        "name": "Bob Jones",
        "is_manager": false
    },
    "state": {
        "id": 350,
        "name": "Review"
    },
    "type": {
        "id": 1,
        "name": "Inventory"
    },
    "ref": "JD192",
    "title": "Inventory & Schedule of Condition",
    "client_id": 4,
    "report_key": "543fe90d312b3",
    "location_of_keys": "With Agent",
    "return_key": "Return to agent",
    "cover_image": {
        "id": 2,
        "url": "http://path/to/image.jpg"
    },
    "notes": {
        "report": null,
        "internal": null,
        "client": "Thanks :)"
    },
    "conduct_date": "2014-10-17T05:30:00",
    "start_date": "2014-10-17T05:25:00",
    "started_at": "2014-10-17T05:25:00",
    "submitted_at": "2014-10-17T06:36:02",
    "completed_at": null,
    "closed_at": null
}

Retrieve a single Inspection by ID.

List all inspections

Request
GET /inspections HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "pagination": {
        "perPage": 10,
        "currentPage": 1,
        "totalPages": 1,
        "totalRecords": 1
    },
    "links": {
        "first": "https://api.inventorybase.com/inspections?page=1",
        "prev": null,
        "self": "https://api.inventorybase.com/inspections?page=1",
        "next": null,
        "last": "https://api.inventorybase.com/inspections?page=1"
    },
    "data": [
        {
            "id": 1,
            "account_id": 1,
            "property": {
                "id": 1,
                "ref": "DEMO00001",
                "address": {
                    "line1": "100 Example Street",
                    "line2": null,
                    "city": "Portsmouth",
                    "county": "Hampshire",
                    "postcode": "PO3 6FY",
                    "country": "United Kingdom"
                },
                "geocoords": {
                    "lat": "50.8148511",
                    "lng": "-1.0965217"
                },
                "furnished": "Unfurnished",
                "type": "House",
                "detachment": "Semi-detached",
                "no_of_beds": 4,
                "no_of_baths": 2,
                "no_of_garages": 1,
                "parking": false,
                "garden": true,
                "notes": "Some notes",
                "client": {
                    "id": 4,
                    "name": "Ali Smith"
                }
            },
            "clerk": {
                "id": 14,
                "name": "Dan Harper",
                "is_manager": true
            },
            "typist": {
                "id": 192,
                "name": "Bob Jones",
                "is_manager": false
            },
            "state": {
                "id": 350,
                "name": "Review"
            },
            "type": {
                "id": 1,
                "name": "Inventory"
            },
            "ref": "JD192",
            "title": "Inventory & Schedule of Condition",
            "client_id": 4,
            "report_key": "543fe90d312b3",
            "location_of_keys": "With Agent",
            "return_key": "Return to agent",
            "cover_image": {
                "id": 2,
                "url": "http://path/to/image.jpg"
            },
            "notes": {
                "report": null,
                "internal": null,
                "client": "Thanks :)"
            },
            "conduct_date": "2014-10-17T05:30:00",
            "start_date": "2014-10-17T05:25:00",
            "started_at": "2014-10-17T05:25:00",
            "submitted_at": "2014-10-17T06:36:02",
            "completed_at": null,
            "closed_at": null
        }
    ]
}

Retrieve a paginated list of all the user's inspections, sorted by creation date - most recent first.

Query Parameters

Field Type Description
client_id int[] Filter for Inspections belonging to specific Clients
clerk_id int[] Filter for Inspections assigned to specific Clerks
property_id int[] Filter for Inspections to only those for the specified properties
address string Filter for Inspections whose full address matches the given input
state_id int[] Inspections in a specific state
conduct_date iso 8601 Date interval

Retrieve Inspection Report

Request
GET /inspections/{inspectionId}/report HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "rooms": [],
    "attachments": {}
}

Access the full report for the inspection. The top-level of the response consists of Rooms and pending attachments. Rooms contain Items and Attachments. Items contain Actions and Attachments.

To the right is an example response of an empty Report object. All objects are returned in the correct order.

Retrieve Inspection Metadata (meters, alarms, keys, manuals)

Request
GET /inspections/{inspectionId}/report/metadata HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "keys": [
        {
            "name": "Keys",
            "location": "Front Door"
        }
    ],
    "manuals": [
        {
            "name": "Oven",
            "description": "Booklet, laminated"
        }
    ],
    "alarms": [
        {
            "name": "Carbon Monoxide",
            "location": "Kitchen",
            "result": "Passed"
        }
    ],
    "meters": [
        {
            "name": "Electric Meter",
            "serial": "EM12",
            "reading": "12345"
        }
    ]
}

Returns metadata related to an inspection.

Response Object

Field Type  
keys Key[]
name string
location string
manuals Manual[]
name string
description string
alarms Alarm[]
name string
location string
result string
meters Meter[]
name string
serial string
reading string

Retrieve Generated PDF

Request

POST /inspections/{inspectionId}/pdf HTTP/1.1

{
    "type": "FULL"
}

Immediate Response

HTTP/1.1 200 OK

{
    "type": "FULL",
    "url": "https://s3.amazonaws..."
}

Delayed Response

HTTP/1.1 202 Accepted

We do not immediately generate PDFs, so when you make this request, you may receive a 200 OK or 202 Accepted response.

  1. If the requested PDF has already been generated, you will receive a 200 response with the url in the JSON body. In this case you will not receive a webhook.

  2. If the PDF has not been generated yet, you will receive a 202 response with no body. Our systems will begin generation in the background, and you'll receive the pdf.generated webhook on completion.

Optionally, you may repeatedly poll the endpoint until you receive a 200 response. To prevent being blocked by the rate limiter, please use a reasonable delay (a few seconds) between retries

Input

Field Type Description
type "FULL" | "CHANGES" | "ACTIONS" Default is "FULL". See the PDF Object for details.

Output (for immediate response only)

Field Type Description
type "FULL" | "CHANGES" | "ACTIONS" Default is "FULL". See the PDF Object for details.
url string The URL of the PDF

Create an Inspection

Request

POST /inspections HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "property": {
        "id": 3
    },
    "type": {
        "id": 1
    },
    "location_of_keys": "With Agent",
    "conduct_date": "2015-06-01T08:15:00.000Z",
    "time_to_complete": "PT1H20M",
    "clerk": {
        "id": 1
    },
    "notes": {
        "internal": "Created via API"
    },
    "preload_template_id": 1,
  "custom_fields': {
    "1": {
      value: "test"
    }
  }
}

Response

{
    "id": 2,
    "account_id": 1,
    "property": {
        "id": 3,
        "ref": "OFJFI2922",
        "address": {
            "line1": "9 Long Street",
            "line2": null,
            "city": "Portsmouth",
            "county": null,
            "postcode": "PO1 3BP",
            "country": "United Kingdom"
        },
        "geocoords": {
            "lat": "50.794844",
            "lng": "-1.104757"
        },
        "furnished": "Unfurnished",
        "type": "Apartment",
        "detachment": null,
        "no_of_beds": 1,
        "no_of_baths": 1,
        "no_of_garages": null,
        "parking": false,
        "garden": false,
        "notes": "Foo bar baz qux",
        "client": null
    },
    "clerk": {
        "id": 1,
        "name": "Dan Harper",
        "is_manager": true
    },
    "typist": null,
    "state": {
        "id": 200,
        "name": "Assigned"
    },
    "type": {
        "id": 1,
        "name": "Inventory"
    },
    "ref": null,
    "title": "Inventory",
    "client_id": null,
    "report_key": "543fe90d3133j",
    "location_of_keys": "With Agent",
    "return_key": null,
    "cover_image": null,
    "notes": {
        "report": null,
        "internal": "Created via API",
        "client": null
    },
    "conduct_date": "2015-06-01",
    "start_date": null,
    "started_at": null,
    "submitted_at": null,
    "completed_at": null,
    "closed_at": null,
  "customFields": {
    "1": {
      "name": "Test field",
      "value: "test",
      "required": false,
    }
  }
}

Perform a POST request to the /inspections endpoint.

Input

Field Type Description
property object
id int Required The ID of the Property the Inspection belongs to
type object
id int Required Inspection Type ID (e.g. 1 = Inventory; 5 = Check Out; etc.)
title string?
location_of_keys string
return_key string | null
conduct_date iso 8601 Required
time_to_complete iso 8601 duration
ref string?
pricing object
price string?
additional string?
margin string?
notes object
internal string?
client string?
clerk object
id int? The ID of a Clerk to assign to the Inspection
preload_template_id int?
auto_load_contacts bool?
auto_load_contacts bool? Automatically include property contacts on the inspection
custom_fields object Value of the custom field
id int The ID of the custom field
value string The value of the custom field

Creating a Live Inspection

Request

POST /inspections HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "self_servicer": {
    "name": "Johnny Tenant",
    "email": "foo@example.com",
    "template_id": null,
  },
  "property": {
    "id": 3
  },
  "type": {
    "id": 231,
  },
  "location_of_keys": "With Agent",
  "conduct_date": "2015-06-01T08:15:00.000Z",
  "time_to_complete": "PT1H20M",
  "notes": {
    "internal": "Created via API"
  }
}

The same as creating an inspection above, with some additional information about the tenant doing the inspection and the correct inspection type.

The inspection type for a live inspection is: 231.

Include self_servicer in the POST request to the /inspections endpoint.

Creating a Self Service Inspection

Request

POST /inspections HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "self_servicer": {
    "name": "Johnny Tenant",
    "email": "foo@example.com",
    "template_id": null,
  },
  "property": {
    "id": 3
  },
  "type": {
    "id": 150,
  },
  "location_of_keys": "With Agent",
  "conduct_date": "2015-06-01T08:15:00.000Z",
  "time_to_complete": "PT1H20M",
  "notes": {
    "internal": "Created via API"
  }
}

The same as creating an inspection above, with some additional information about the tenant doing the inspection, the correct inspection type, and a valid self service template.

The inspection type for self service is: 150. If the template_id is null, the system will use the default Self Service template (see below on how to locate a template for self service).

Include self_servicer in the POST request to the /inspections endpoint.

Finding a Self Service template

Request

GET /settings/account/self-service/templates HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response

{
    "system": [
        {
            "id": 1,
            "name": "Self Service"
        }
    ],
    "account": [
        {
            "id": 2,
            "name": "Self Service Custom"
        }
    ]
}

A GET request to the /settings/account/self-service/templates endpoint will return two arrays: one of the system self service templates and one for the account. The id should be used to set a template for self service.

Update an Inspection

Request

PUT /inspections/2 HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "conduct_date": "2015-06-01T08:15:00.000Z",
    "time_to_complete": "PT1H20M",
    "clerk": {
        "id": 1
    },
    "notes": {
        "internal": "Updated via API"
    },
  "custom_fields': {
    "1": {
      value: "test"
    },
    "2": {
      value: "Yes"
    }
  }
}

Response

{
    "id": 2,
    "account_id": 1,
    "property": {
        "id": 3,
        "ref": "OFJFI2922",
        "address": {
            "line1": "9 Long Street",
            "line2": null,
            "city": "Portsmouth",
            "county": null,
            "postcode": "PO1 3BP",
            "country": "United Kingdom"
        },
        "geocoords": {
            "lat": "50.794844",
            "lng": "-1.104757"
        },
        "furnished": "Unfurnished",
        "type": "Apartment",
        "detachment": null,
        "no_of_beds": 1,
        "no_of_baths": 1,
        "no_of_garages": null,
        "parking": false,
        "garden": false,
        "notes": "Foo bar baz qux",
        "client": null
    },
    "clerk": {
        "id": 1,
        "name": "Dan Harper",
        "is_manager": true
    },
    "typist": null,
    "state": {
        "id": 200,
        "name": "Assigned"
    },
    "type": {
        "id": 1,
        "name": "Inventory"
    },
    "ref": null,
    "title": "Inventory",
    "client_id": null,
    "report_key": "543fe90d3133j",
    "location_of_keys": "With Agent",
    "return_key": null,
    "cover_image": null,
    "notes": {
        "report": null,
        "internal": "Updated via API",
        "client": null
    },
    "conduct_date": "2015-06-01",
    "start_date": null,
    "started_at": null,
    "submitted_at": null,
    "completed_at": null,
    "closed_at": null,
  "customFields": {
    "1": {
      "name": "Test field",
      "value: "test",
      "required": false,
    },
    "2": {
      "name": "Tenant present",
      "value": "Yes",
      "required": "false"
    }
  }
}

Perform a PUT request to the /inspections/{inspectionId} endpoint.

Input should contain the fields which need to be updated.

Cancel an Inspection

Request

POST /inspections HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response

{
    "id": 2,
    "account_id": 1,
    "property": {
        "id": 3,
        "ref": "OFJFI2922",
        "address": {
            "line1": "9 Long Street",
            "line2": null,
            "city": "Portsmouth",
            "county": null,
            "postcode": "PO1 3BP",
            "country": "United Kingdom"
        },
        "geocoords": {
            "lat": "50.794844",
            "lng": "-1.104757"
        },
        "furnished": "Unfurnished",
        "type": "Apartment",
        "detachment": null,
        "no_of_beds": 1,
        "no_of_baths": 1,
        "no_of_garages": null,
        "parking": false,
        "garden": false,
        "notes": "Foo bar baz qux",
        "client": null
    },
    "clerk": {
        "id": 1,
        "name": "Dan Harper",
        "is_manager": true
    },
    "typist": null,
    "state": {
        "id": 200,
        "name": "Assigned"
    },
    "type": {
        "id": 1,
        "name": "Inventory"
    },
    "ref": null,
    "title": "Inventory",
    "client_id": null,
    "report_key": "543fe90d3133j",
    "location_of_keys": "With Agent",
    "return_key": null,
    "cover_image": null,
    "notes": {
        "report": null,
        "internal": "Created via API",
        "client": null
    },
    "conduct_date": "2015-06-01",
    "start_date": null,
    "started_at": null,
    "submitted_at": null,
    "completed_at": null,
    "closed_at": null
}

Perform a POST request to the /inspections/{inspectionId}/cancel endpoint.

Copying an Inspection Report from another Property

PUT /inspections/{inspectionId}/report/copy-from-property/{sourcePropertyId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "mode": "append"
}

Response

{
    "rooms": [
        /* Rooms copied from Property */
    ],
    "attachments": {}
}

Perform a PUT request to the /copy-from-property endpoint.

There are two "modes" when copying a report from another Property. The append mode will add the copied Rooms after any existing Rooms on the Report. This mode is the default, so does not need to be specified in the request.

The reset mode will remove all existing Rooms from the Report, then add the copied Rooms.

Input

Field Input Description
mode string? The mode of the copy - either append or reset

Changing Inspection Initialization

PUT /inspections/{inspectionId}/initialization
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "type": 6,
  "init_from" 109616,
}

Response

{
    "id": 2,
    "account_id": 1,
    "property": {
        "id": 3,
        "ref": "OFJFI2922",
        "address": {
            "line1": "9 Long Street",
            "line2": null,
            "city": "Portsmouth",
            "county": null,
            "postcode": "PO1 3BP",
            "country": "United Kingdom"
        },
        "geocoords": {
            "lat": "50.794844",
            "lng": "-1.104757"
        },
        "furnished": "Unfurnished",
        "type": "Apartment",
        "detachment": null,
        "no_of_beds": 1,
        "no_of_baths": 1,
        "no_of_garages": null,
        "parking": false,
        "garden": false,
        "notes": "Foo bar baz qux",
        "client": null
    },
    "clerk": {
        "id": 1,
        "name": "Dan Harper",
        "is_manager": true
    },
    "typist": null,
    "state": {
        "id": 200,
        "name": "Assigned"
    },
    "type": {
        "id": 1,
        "name": "Inventory"
    },
    "ref": null,
    "title": "Inventory",
    "client_id": null,
    "report_key": "543fe90d3133j",
    "location_of_keys": "With Agent",
    "return_key": null,
    "cover_image": null,
    "notes": {
        "report": null,
        "internal": "Created via API",
        "client": null
    },
    "conduct_date": "2015-06-01",
    "start_date": null,
    "started_at": null,
    "submitted_at": null,
    "completed_at": null,
    "closed_at": null,
    "initialized": true,
    "initialization": {
        "type": 6,
        "id": 33,
        "date": "2019-01-29T08:58:56+00:00"
    }
}

Perform a PUT request to the /initialization endpoint.

This will change the initialization of the inspection. It cannot be done after the inspection has already been started/initialized.

Input

Field Input Description
init_from integer? ID of the inspection or template to initialise from. If left null will remove the current initialization.
type integer? Type of initialization - from inspection (6) or from template (3)

Contacts

Contacts are assigned to an Inspection or a Property.

The Contact object

{
    "id": 1,
    "type": 1,
    "name": "John",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": false
}
Field Type Description
id int Unique identifier for the object
type int The type of contact (see below) Required
name string The name of the contact Required
email string The email address of the contact
phone string The phone number of the contact
signee bool The contact is a signee Required
notify bool The contact will be notified of scheduling and changes to the inspection Required
deliver bool The contact will be sent the completed report Required

Possible Contact Types

ID Type
1 Tenant
2 Agent
3 Landlord
4 Witness
5 Clerk
6 Other

List contacts for an Inspection

Request
GET /inspections/{inspectionId}/contacts HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
[
    {
        "id": 1,
        "type": 1,
        "name": "John",
        "email": "example@radweb.co.uk",
        "phone": "01234 567890",
        "signee": true,
        "notify": true,
        "deliver": false
    }
]

List contacts for a Property

Request
GET /properties/{propertyId}/contacts HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
[
    {
        "id": 1,
        "type": 1,
        "name": "John",
        "email": "example@radweb.co.uk",
        "phone": "01234 567890",
        "signee": true,
        "notify": true,
        "deliver": false
    }
]

Retrieve a list of all the property's contacts.

Retrieve Tenant's External Maintenance Link

Request
GET /properties/{propertyId}/contacts/{contactId}/tenant-action-url HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "url": "https://api.inventorybase.com/maintenance/some-key",
}

Retrieve the Tenant's external maintenance link

Create an Inspection Contact

Request

POST /inspections/{inspectionId}/contacts HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "type": 1,
    "name": "John",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": false
}

Response

{
    "id": 1,
    "type": 1,
    "name": "John",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": false
}

Perform a POST request to the /inspections/{inspectionId}/contacts endpoint.

Update an Inspection Contact

Request

PUT /inspections/{inspectionId}/contacts/{contactId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "type": 1,
    "name": "Julie",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": true
}

Response

{
    "id": 1,
    "type": 1,
    "name": "Julie",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": true
}

Perform a PUT request to the /inspections/{inspectionId}/contacts/{contactId} endpoint.

Delete an Inspection Contact

Request

DELETE /inspections/{inspectionId}/contacts/{contactId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

{
    "id": 1,
    "type": 1,
    "name": "Julie",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": true
}

Perform a DELETE request to the /inspections/{inspectionId}/contacts/{contactId} endpoint.

Create a Property Contact

Request

POST /properties/{propertyId}/contacts HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "type": 1,
    "name": "John",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": false
}

Response

{
    "id": 1,
    "type": 1,
    "name": "John",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": false
}

Perform a POST request to the /properties/{propertyId}/contacts endpoint.

Update a Property Contact

Request

PUT /properties/{propertyId}/contacts/{contactId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "type": 1,
    "name": "Julie",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": true
}

Response

{
    "id": 1,
    "type": 1,
    "name": "Julie",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": true
}

Perform a PUT request to the /properties/{propertyId}/contacts/{contactId} endpoint.

Delete a Property Contact

Request

DELETE /properties/{propertyId}/contacts/{contactId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

{
    "id": 1,
    "type": 1,
    "name": "Julie",
    "email": "example@radweb.co.uk",
    "phone": "01234 567890",
    "signee": true,
    "notify": true,
    "deliver": true
}

Perform a DELETE request to the /properties/{propertyId}/contacts/{contactId} endpoint.

Rooms

A Report consists of many Rooms. A "Room" may not necessarily be an actual room in a property (although most are). You can think of them instead as "Blocks", which may be a Room, or details of Keys, Meter Readings etc. The type of room block this is, is defined by the block_type field.

Names of Rooms are only editable during the initial Inspection. Due to this, the name field is represented as an Object with two properties: value (the actual value) and editable (boolean defining if the name can be edited).

Possible Block Types

CAUTION! New Block Types may be added with little to no notice, so be sure to code your application to degrade gracefully when encountering an unknown Block Type (e.g. skipping it, or marking it as "unsupported" in your UI)

Option Sets

{
    "id": 1,
    "name": "Clean/Undamaged/Working",
    "editable": false,
    "options": ["Clean", "Undamaged", "Working"]
}

Rooms of the following Block Types include an "Option Set":

For Items within Rooms of these Block Types, the Option Set is used as seed data for the items' condition (see Items for more details).

The Room object

{
    "id": 2,
    "name": {
        "value": "Bathroom",
        "editable": false
    },
    "block_type": "SCALE",
    "option_set": {
        "id": 2,
        "name": "3 Star Rating",
        "editable": false,
        "options": [1, 2, 3]
    },
    "items": [],
    "attachments": []
}
Field Type Description
id int Unique identifier for the object
name object
value string The name of the Room
editable boolean Whether the name can be modified (if false, changes sent to the API will be ignored)
block_type string One of the possible Block Types
option_set object | null
id int ID of the Option Set used on the Room
name string A user-friendly name of the Option Set
editable boolean Whether the Option Set can be modified
options string[] | int[] The options allowed for conditions on Items within the Room
items Item[] An array of Item objects
attachments Attachment[] An array of Attachment objects

Creating a Room

Request (DETAILED)

POST /inspections/{inspectionId}/rooms HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "name": "Master Bedroom",
  "block_type": "DETAILED"
}

Response (DETAILED)

{
    "id": 3,
    "name": {
        "value": "Master Bedroom",
        "editable": true
    },
    "block_type": "DETAILED",
    "items": [],
    "attachments": []
}

Request (SIMPLIFIED)

POST /inspections/{inspectionId}/rooms HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "name": "Kitchen",
  "block_type": "SIMPLIFIED",
  "option_set": 1
}

Response (SIMPLIFIED)

{
    "id": 4,
    "name": {
        "value": "Kitchen",
        "editable": true
    },
    "block_type": "SIMPLIFIED",
    "option_set": {
        "id": 1,
        "name": "Clean/Undamaged/Working",
        "editable": false,
        "options": ["Clean", "Undamaged", "Working"]
    },
    "items": [],
    "attachments": []
}

Perform a POST request against the /room endpoint on an Inspection. You'll receive your newly created Room object.

Input

Field Input Description
name string Required The name of the Room/Block; e.g. "Bedroom", "Schedule of Condition", "Meter Readings"
block_type string Required One of the accepted block_type values
option_set int? ID of an Option Set, required only for SIMPLIFIED and SCALE Block Types

Modifying a Room

Request

PUT /inspections/{inspectionId}/rooms/{roomId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "name": "Bedroom"
}

Response

{
    "id": 3,
    "block_type": "DETAILED",
    "name": {
        "value": "Bedroom",
        "editable": true
    },
    "items": [],
    "attachments": []
}

Perform a PUT request against the Room's endpoint. You can only modify the name (if it is editable) - the block_type or option_set can not be changed once set.

Input

Field Input Description
name string Required The name of the Room/Block; e.g. "Bedroom", "Schedule of Condition", "Meter Readings"

Deleting a Room

Request

DELETE /inspections/{inspectionId}/rooms/{roomId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

/* nothing (even this isn't there) */

A simple DELETE request against the Rooms's endpoint will do the trick. This will also delete all Items/Attachments/Actions assigned to the Room.

You won't receive a response body. Just 200 status code if all was well.

Re-ordering Rooms within a Report

Request

PUT /inspections/{inspectionId}/rooms HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

[3, 1, 2, 9, 7]

Response

[3, 1, 2, 9, 7]

To re-order Rooms within an Inspection, send up an array of the Room IDs in the new order to the root /rooms endpoint on an Inspection.

You will receive a 200 response with the same order array in the body if it was successful.

Items

DETAILED, OVERVIEW & METERS Condition

{
    "value": "Foo bar",
    "editable": true
}

SIMPLIFIED Condition

{
    "value": {
        "Clean": 1,
        "Undamaged": 0,
        "Working": 2
    },
    "editable": true
}

CHECKLIST Condition

{
    "value": 1,
    "editable": true
}

SCALE Condition

{
    "value": 4,
    "editable": true
}

KEYS & MANUALS do not have Conditions

{
    "value": null,
    "editable": false
}

Items represent physical Items within individual Rooms of a Property. On a base level, they have a Name, Description and Condition. They can also have Actions and Attachments associated with them.

We can represent Items in many ways, which are defined by the containing Room's block_type field.

In every case, the Name, Description and Condition may not be editable on the currently loaded Inspection. For example, Names are only editable during the initial Inspection. Due to this, each of these are represented as an Object with two properties: value (the actual value) and editable (boolean).

The Item object

An Item in a "DETAILED" Room
{
    "id": 13,
    "name": {
        "value": "Shower",
        "editable": true
    },
    "description": {
        "value": "White shower cubicle something something",
        "editable": true
    },
    "condition": {
        "value": "Brand new; Scuff to bottom edge",
        "editable": true
    },
    "actions": [],
    "attachments": []
}
An Item in a "SIMPLIFIED" Room
{
    "id": 14,
    "name": {
        "value": "Front Door",
        "editable": false
    },
    "description": {
        "value": null,
        "editable": true
    },
    "condition": {
        "value": {
            "Clean": 1,
            "Undamaged": 0,
            "Working": null,
            "Something": 2
        },
        "editable": true
    },
    "actions": [],
    "attachments": []
}

see above for conditions in other block types

Field Type Description
id int Unique identifier for the object
name object
value string The name of the Item
editable boolean Whether the name can be modified (if false, changes sent to the API will be ignored)
description object
value string The description of the Item
editable boolean Whether the description can be modified (if false, changes sent to the API will be ignored)
condition object
If the containing room has block_type of DETAILED, the condition is a free-text field:

value string The condition of the Item
editable boolean Whether the condition can be modified (if false, changes sent to the API will be ignored)

If the containing room has block_type of SIMPLIFIED, the condition is a series of pre-determined questions to be answered:

value object An object consisting of Question-Answer key-value pairs. Answers must be one of: 0 (No), 1 (Yes), 2 (N/A) or null (unanswered).
editable boolean Whether the condition can be modified (if false, changes sent to the API will be ignored)
actions Action[] An array of Action objects
attachments Attachment[] An array of Attachment objects

Creating an Item

Request - in a "DETAILED" Room

POST /inspections/{inspectionId}/rooms/{roomId}/items HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "name": "Kingsize Bed",
  "description": "Hemnes Black/Brown IKEA",
  "condition": "Pristine condition; Something else"
}

Response - in a "DETAILED" Room

{
    "id": 1,
    "name": {
        "value": "Kingsize Bed",
        "editable": true
    },
    "description": {
        "value": "Hemnes Black/Brown IKEA",
        "editable": true
    },
    "condition": {
        "value": "Pristine condition; Something else",
        "editable": true
    },
    "actions": [],
    "attachments": []
}

Request - in a "SIMPLIFIED" Room

POST /inspections/{inspectionId}/rooms/{roomId}/items HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "name": "Kingsize Bed",
  "description": "Hemnes Black/Brown IKEA",
  "condition": {
    "Clean": 1,
    "Undamged": 1,
    "Working": 1,
    "Something": null
  }
}

Response - in a "SIMPLIFIED" Room

{
    "id": 1,
    "name": {
        "value": "Kingsize Bed",
        "editable": true
    },
    "description": {
        "value": "Hemnes Black/Brown IKEA",
        "editable": true
    },
    "condition": {
        "value": {
            "Clean": 1,
            "Undamged": 1,
            "Working": 1,
            "Something": null
        },
        "editable": true
    },
    "actions": [],
    "attachments": []
}

Simply perform a POST request against the /items endpoint on an Room.

Input

Field Input Description
name string Required The name of the Item; e.g. "Bed"
description string A short description of the Item e.g. describing the colour, size
condition string | int | object A valid condition according to the block type of the containing room

Modifying an Item

Request - in a "DETAILED" Room

PUT /inspections/{inspectionId}/rooms/{roomId}/items/{itemId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "name": "Kingsize Bed",
  "description": "Hemnes Black/Brown IKEA",
  "condition": null
}

Response - in a "DETAILED" Room

{
    "id": 1,
    "name": {
        "value": "Kingsize Bed",
        "editable": true
    },
    "description": {
        "value": "Hemnes Black/Brown IKEA",
        "editable": true
    },
    "condition": {
        "value": null,
        "editable": true
    },
    "actions": [],
    "attachments": []
}

Perform a PUT request against the Item's endpoint.

Input

Field Input Description
name string Required The name of the Item; e.g. "Bed"
description string A short description of the Item e.g. describing the colour, size (if field is missing, description will be cleared)
condition string | int | object A valid condition according to the block type of the containing room

Deleting an Item

Request

DELETE /inspections/{inspectionId}/rooms/{roomId}/items/{itemId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

/* nothing (even this isn't there) */

A simple DELETE request against the Item's endpoint will do the trick.

You won't receive a response body. Just 200 status code if all was well.

Re-ordering Items within a Room

Request

PUT /inspections/{inspectionId}/rooms/{roomId}/items HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

[4, 8, 12, 1, 3]

Response

[4, 8, 12, 1, 3]

To re-order Items within a Room, send up an array of the Item IDs in the new order to the root /items endpoint on a Room.

You will receive a 200 response with the same order array in the body if it was successful.

Copying an Item

Request - Copying to existing Room

PUT /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/copy HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "room": {
    "id": 1
  }
}

Response

{
    "id": 1,
    "name": {
        "value": "Double Wardrobe",
        "editable": true
    },
    "description": {
        "value": "Oak Double Wardrobe with Clothes Rail",
        "editable": true
    },
    "condition": {
        "value": null,
        "editable": true
    },
    "actions": [],
    "attachments": []
}

Request - Copying to a new Room

PUT /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/copy HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "room": {
    "name": "Double Wardrobe COPY"
  }
}

Response

{
    "id": 1,
    "name": {
        "value": "Double Wardrobe COPY",
        "editable": true
    },
    "description": {
        "value": "Oak Double Wardrobe with Clothes Rail",
        "editable": true
    },
    "condition": {
        "value": null,
        "editable": true
    },
    "actions": [],
    "attachments": []
}

Perform a PUT request against the Item's copy endpoint. This will copy the Item specified in the URL to the Room specified in the request body.

If specifying a name, a new Room will be created with the Item copied into it. The new Room's Block Type will match the source Room's Block Type. If specifying an id in the request body, the Item will be copied to the existing Room with that id.

Additionally, if copying to an existing Room, a overwrite_id can be specified. An Item with an id matching the overwrite_id will update the matching Item's description & condition in the existing Room.

Input

Field Type Description
room object
id int? The id of the existing Room. Only use if copying to an existing Room
name string? The name of the new Room. Only use if copying to an existing Room
overwrite_id int? Id of Item to be overwritten in existing Room

Actions

Actions are additional data stored against individual Items on a per-Inspection basis (they do not fall through to later Inspections).

For example, if an Item is in a state of disrepair, the Clerk may recommend that "Actions" be performed by a certain party - such as "Needs Repair" by "Tenant", with any additional comments.

On generated Reports, these Actions from every Item may be aggregated at the bottom to produce a block of everything which needs to be carried out.

The Action object

{
    "id": 1,
    "action": "Needs Maintenance",
    "responsibility": "Tenant",
    "comments": "Fix up the scuffs"
}
Field Type Description
id int Unique identifier for the object
action string What needs undertaking on an Item; e.g. "Needs Maintenace", "Needs Cleaning"
responsibility string Who is responsible; e.g. "Tenant", "Landlord", "Agent"
comments string | null Additional comments regarding this action

Adding an Action to an Item

Request

POST /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/actions HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "action": "Needs Cleaning",
  "responsibility": "Tenant",
  "comments": "It's absolutely filthy"
}

Response

{
    "id": 3,
    "action": "Needs Cleaning",
    "responsibility": "Tenant",
    "comments": "It's absolutely filthy"
}

Simply perform a POST request against the /actions endpoint on an Item.

Input

Field Input Description
action string Required The action will needs undertaking on the Item, e.g. "Needs Cleaning" or "Needs Repairing"
responsbility string Required Who is reponsibile? e.g. "Tenant", "Landlord", "N/A" etc.
comments string? Any additional comments regarding this action

Modifying an Action

Request

PUT /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/actions/{actionId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "action": "Needs Cleaning",
  "responsibility": "Landlord",
  "comments": null
}

Response

{
    "id": 3,
    "action": "Needs Cleaning",
    "responsibility": "Landlord",
    "comments": null
}

Perform a PUT request against the Action's endpoint.

Input

Field Input Description
action string Required The action will needs undertaking on the Item, e.g. "Needs Cleaning" or "Needs Repairing"
responsbility string Required Who is reponsibile? e.g. "Tenant", "Landlord", "N/A" etc.
comments string Any additional comments regarding this action (if field is missing, comments will be cleared)

Delete an Action

Request

DELETE /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/actions/{actionId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

/* nothing (even this isn't there) */

Perform a DELETE request against the Action's endpoint.

DELETE requests do not return data. Get a 200 code and you're all good.

List Actions for a Property

Request

GET /properties/{propertyId}/actions HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

;[
    {
        id: 123,
        uuid: 'ddaa5b51-acc9-4d39-97eb-28282a7d9ed3',
        action: 'Needs Cleaning',
        responsbility: 'Tenant',
        comments: 'Coffee stains on table.',
        note: 'Professional clean required.',
        value: 5000,
        completed_at: '2021-11-12T15:36:40Z',
        inspection: {
            id: 1000000,
            title: 'Inventory & Schedule of Condition',
            conductDate: '2021-11-12T15:37:35Z',
        },
        room: {
            id: 20000000,
            name: 'Dining Room',
        },
        item: {
            id: 100000000,
            name: 'Dining Table',
        },
    },
]

Perform a GET request against the Property Action's endpoint.

This endpoint will return an array of Action objects, including partial inspection, room, and item data each action relates to.

List Actions for an Inspection

Request

GET /inspections/{inspectionId}/actions HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

;[
    {
        id: 123,
        uuid: 'ddaa5b51-acc9-4d39-97eb-28282a7d9ed3',
        action: 'Needs Cleaning',
        responsbility: 'Tenant',
        comments: 'Coffee stains on table.',
        note: 'Professional clean required.',
        value: 5000,
        completed_at: '2021-11-12T15:36:40Z',
        inspection: {
            id: 1000000,
            title: 'Inventory & Schedule of Condition',
            conductDate: '2021-11-12T15:37:35Z',
        },
        room: {
            id: 20000000,
            name: 'Dining Room',
        },
        item: {
            id: 100000000,
            name: 'Dining Table',
        },
    },
]

Perform a GET request against the Inspection Action's endpoint.

This endpoint will return an array of Action objects, including partial room and item data each action relates to.

Action Reports

Action Reports group actions by responsibility or task to provide a schedule of work, cost estimates, and track which actions have been completed.

For example, a Clerk may deliver an Action Report to the Landlord or property manager detailing all tasks that need to be undertaken to keep the property in good repair.

The Action Report object

{
    "id": 1,
    "report_key": "263b6a81-9ecb-4c5c-a498-0f48d9e899b2",
    "inspection_id": 1000000,
    "responsibilities": ["Tenant", "Landlord", "Agent", "Investigate", "N/A"]
}
Field Type Description
id int Unique identifier for the object
report_key string Identifier used to access the report's URL
inspection_id int ID of the Inspection this report relates to
responsibilities string[] Array of responsibilities included in this report

List Action Reports by Inspection

Request

GET /inspections/{inspectionId}/action-reports HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

;[
    {
        id: 1,
        inspection_id: 2000000,
        report_key: '5d5a5618-44c5-436d-b037-2a070ca120ee',
        responsiblities: ['Tenant', 'Landlord'],
    },
]

Perform a GET request against the Inspection's Action Report endpoint

This endpoint will return an array of Action Report objects relating to the Inspection requested.

Attachments

An Attachment may be an IMAGE, VIDEO, AUDIO or FILE. They can be attached to an Item, Room or an Inspection Report itself. Attachments are rarely attached to the Inspection itself, but may be done to provide a Cover Image, or provide exterior images where no "Exterior" Room Block exists.

The Attachment object

{
    "id": 8,
    "type": "IMAGE",
    "url": "https://s3.amazonaws.com/.....030bb7bade.png",
    "description": "3 - Properties",
    "taken_at": "2014-10-21T14:30:49"
}
Field Type Description
id int Unique identifier for the object
type string One of: "IMAGE", "VIDEO", "AUDIO" or "FILE"
url string The URL the attachment is located at
description string | null Additional description of the attachment
taken_at iso 8601 | null Date the attachment was created (on the device, not uploaded)

Creating an Attachment

Request - Inspection Endpoint

POST /inspections/{inspectionId}/attachments HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Request - Room Endpoint

POST /inspections/{inspectionId}/rooms/{roomId}/attachments HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Request - Item Endpoint

POST /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/attachments HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Request Body

{
  "description": "Bathroom mirror",
  "upload": /* the file's body */
}

Response

{
    "id": 9,
    "type": "IMAGE",
    "url": "https://s3.amazonaws.com/.....030bb7bade.png",
    "description": "Bathroom mirror",
    "taken_at": "2014-10-21T14:30:49"
}

The endpoint you POST to will depend on what you're attaching the upload to.

You must upload the file's content as multipart/form-data, with the file's body keyed as upload.

The server will work out your file's "type", and extract the date it was created.

Input

Field Input Description
description string | null An optional description of the upload
upload The file itself

Modifying an Attachment's description

Not Yet Implemented

The documentation below is just an idea of how it may work.

Contact support if you require these endpoints, and we'll attempt to prioritise their development.

Request - Inspection Endpoint

PUT /inspections/{inspectionId}/attachments/{attachmentId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "description": "Foo bar"
}

Request - Room Endpoint

PUT /inspections/{inspectionId}/rooms/{roomId}/attachments/{attachmentId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "description": "Foo bar"
}

Request - Item Endpoint

PUT /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/attachments/{attachmentId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "description": "Foo bar"
}

Response

{
    "id": 9,
    "type": "IMAGE",
    "url": "https://s3.amazonaws.com/.....030bb7bade.png",
    "description": "Foo bar",
    "taken_at": "2014-10-21T14:30:49"
}

The endpoint you PUT to will depend on where the upload was attached to. You can not change an attachment to be another upload - you must delete the original and upload a new attachment.

Input

Field Input Description
description string | null An optional description of the upload

Rotating an Attachment

Request

PUT /attachments/{attachmentId}/rotation HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "angle": 90
}

Response

{
    "id": 9,
    "type": "IMAGE",
    "url": "https://s3.amazonaws.com/.....030bb7bade.png",
    "description": "Foo bar",
    "taken_at": "2014-10-21T14:30:49"
}

Perform a PUT request against the Attachment's rotation endpoint. Note: rotation is clockwise.

Input

Field Input Description
angle int Required Angle to rotate the image by (rotates clockwise)

Assigning an Attachment to another Room/Item

Request - Assignment to Inspection Report endpoint

PUT /attachments/{attachmentId}/assign HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

{
    "id": 9,
    "type": "IMAGE",
    "url": "https://s3.amazonaws.com/.....030bb7bade.png",
    "description": "Foo bar",
    "taken_at": "2014-10-21T14:30:49"
}

Request - Assignment to Room endpoint

PUT /attachments/{attachmentId}/assign HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "room_id": 5
}

Response

{
    "id": 9,
    "type": "IMAGE",
    "url": "https://s3.amazonaws.com/.....030bb7bade.png",
    "description": "Foo bar",
    "taken_at": "2014-10-21T14:30:49"
}

Request - Assignment to Item endpoint

PUT /attachments/{attachmentId}/assign HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
  "room_id": 6,
  "item_id": 2
}

Response

{
    "id": 9,
    "type": "IMAGE",
    "url": "https://s3.amazonaws.com/.....030bb7bade.png",
    "description": "Foo bar",
    "taken_at": "2014-10-21T14:30:49"
}

Perform a PUT request against the Attachment's assignment endpoint. To assign to an Item, pass the relevant room_id and item_id in the request. To assign to a Room, pass only the relevant room_id. To assign to an Inspection Report, leave off both the room_id and item_id fields.

Input

Field Input Description
room_id int Id of the Room to assign the attachment to (do not include if assigning to Inspection)
item_id int Id of the Item to assign the attachment to (do not include if assigning to Room)

Deleting an Attachment

Not Yet Implemented

The documentation below is just an idea of how it may work.

Contact support if you require these endpoints, and we'll attempt to prioritise their development.

Request - Inspection Endpoint

DELETE /inspections/{inspectionId}/attachments HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Request - Room Endpoint

DELETE /inspections/{inspectionId}/rooms/{roomId}/attachments HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Request - Item Endpoint

DELETE /inspections/{inspectionId}/rooms/{roomId}/items/{itemId}/attachments HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

Response

/* nothing (even this isn't there) */

A simple DELETE request against the Attachment's endpoint will do the trick.

You won't receive a response body. Just 200 status code if all was well.

File Sharing

A file share can be created for any documents uploaded to a property or inspection.

A file share should be publicly accessed via the following URL https://api.inventorybase.com/file-sharing/{linkId}

The File Share object

{
    "id": 1,
    "linkId": "eyJpdiI6IkFQRThFV2tndHFiKzBzS1F0SzkrcUE9PSIsInZhbHVlIjoic2QxVk5WRnBxdFcrM0JLTlIzQXVIZ2k2WDdVT2lOSW5DR2RSRm5BNkluS2ZXYVhHK3RSZ2xFVldBRzV2Vlo1TUdITkRhK0RLdGFPUk5ORHhqcUViU1E9PSIsIm1hYyI6Ijc0NmQ1YWJhOWQzNGYzZTlmMDNmNjRmODgxYTc1OTJhMzQ5NjQxZTg4NDFmY2QyNWQ1YzBiNjc1ZmU3ZTA3MWYifQ==",
    "alias": "For Rich",
    "inspectionId": 1,
    "attachmentId": 3,
    "propertyId": null,
    "firstAccessedAt": "August 31st 08:19",
    "lastAccessedAt": "August 31st 08:49"
}
Field Type Description
id int Unique identifier for the object
linkId string Base64 encoded id used in the sharable link
alias string / null Optional, human friendly alias used for identifying a link
inspectionId number / null The inspection ID the file share relates to
attachmentId number / null The attachment ID the file share relates to
propertyId number / null The property ID the file share relates to
firstAccessedAt string / null Formatted datetime of the first time the file share was accessed
lastAccessedAt string / null Formatted datetime of the last time the file share was accessed

Creating a file share

REQUEST

POST /file-share/{attachmentId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

REQUEST BODY

{
    "alias": "For Matt",
    "inspectionId": 1,
    "propertyId": null
}

RESPONSE

{
    "id": 16,
    "linkId": "eyJpdiI6Ikh4RUdlUUFSWHJoeURKV2N4aFFIRWc9PSIsInZhbHVlIjoieFFtaU9XbDVHNVNBOWxPc0xXU2ZXYXo0Nkt6cVQ5SWZyOVVRdTZ3cW96RnFWYTBmWWNrMk1VSkhaVkZEZThsSzJvRDJhWDBkTThOTURNbUZmSEhkVkE9PSIsIm1hYyI6ImQzMDFlNmQ4NTEyYTkyMTlmYTc2YWU5ZjQ4ZmU5ZTdiOWE1N2JmZjY1ZWFjOTYyNjAzNTBiYzU1YzUzZjE0NjMifQ==",
    "alias": "For Matt",
    "inspectionId": 1,
    "attachmentId": 55,
    "propertyId": null,
    "firstAccessedAt": null,
    "lastAccessedAt": null
}

This endpoint takes a POST containing JSON data.

You must supply either an inspection ID or a property ID.

Path Parameters

Field Type Description
attachmentId string The ID of the attachment for the file share to reference

Request Body

Field Type Description
alias string / null Optional alias for the file share
inspectionId string / null Inspection ID the file share relates to
propertyId string / null Property ID the file share relates to

Getting a file share

REQUEST

GET /file-share/{attachmentId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

RESPONSE

{
    "id": 16,
    "linkId": "eyJpdiI6Ikh4RUdlUUFSWHJoeURKV2N4aFFIRWc9PSIsInZhbHVlIjoieFFtaU9XbDVHNVNBOWxPc0xXU2ZXYXo0Nkt6cVQ5SWZyOVVRdTZ3cW96RnFWYTBmWWNrMk1VSkhaVkZEZThsSzJvRDJhWDBkTThOTURNbUZmSEhkVkE9PSIsIm1hYyI6ImQzMDFlNmQ4NTEyYTkyMTlmYTc2YWU5ZjQ4ZmU5ZTdiOWE1N2JmZjY1ZWFjOTYyNjAzNTBiYzU1YzUzZjE0NjMifQ==",
    "alias": "For Matt",
    "inspectionId": 1,
    "attachmentId": 55,
    "propertyId": null,
    "firstAccessedAt": null,
    "lastAccessedAt": null
}

This endpoint takes a GET and retrieves all the file shares for an attachment.

Path Parameters

Field Type Description
attachmentId string The ID of the attachment referenced

Updating a file share

REQUEST

PUT /file-share/{fileShareId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

REQUEST BODY

{
    "alias": "For Jacek"
}

RESPONSE

{
    "id": 16,
    "linkId": "eyJpdiI6Ikh4RUdlUUFSWHJoeURKV2N4aFFIRWc9PSIsInZhbHVlIjoieFFtaU9XbDVHNVNBOWxPc0xXU2ZXYXo0Nkt6cVQ5SWZyOVVRdTZ3cW96RnFWYTBmWWNrMk1VSkhaVkZEZThsSzJvRDJhWDBkTThOTURNbUZmSEhkVkE9PSIsIm1hYyI6ImQzMDFlNmQ4NTEyYTkyMTlmYTc2YWU5ZjQ4ZmU5ZTdiOWE1N2JmZjY1ZWFjOTYyNjAzNTBiYzU1YzUzZjE0NjMifQ==",
    "alias": "For Jacek",
    "inspectionId": 1,
    "attachmentId": 55,
    "propertyId": null,
    "firstAccessedAt": null,
    "lastAccessedAt": null
}

This endpoint takes a PUT and updates the file share.

Path Parameters

Field Type Description
fileShareId string The ID of the file share to update

Request Body

Field Type Description
alias string / null Optional alias for the file share

Deleting a file share

REQUEST

PUT /file-share/{fileShareId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

This endpoint takes a DELETE and deletes a file share.

Path Parameters

Field Type Description
fileShareId string The ID of the file share to update

Getting all file shares for all of a properties attachments

GET /file-share/property/{propertyId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

RESPONSE

[
    {
        "attachment": {
            "id": 56,
            "uuid": "023ac49d-0285-48e1-a0ae-24071b230b69",
            "type": "image",
            "type_id": 1,
            "url": "https://inventorybase-stage.s3.eu-west-1.amazonaws.com/attachments/1/1/7a7572cc-6161-4433-b295-b2f62c4c5a8b.jpg",
            "thumbnail": "https://inventorybase-stage.s3.eu-west-1.amazonaws.com/attachments/1/1/7a7572cc-6161-4433-b295-b2f62c4c5a8b-thumbnail.jpg",
            "description": "20220826_152537.jpg",
            "taken_at": null,
            "metadata": {
                "360": false,
                "page_count": null,
                "uploaded_by_tenant": false,
                "hide_on_report": false,
                "shown_on_report": false,
                "document_name": null
            },
            "room_id": null,
            "item_id": null,
            "previous_attachment_ids": [],
            "inspection_id": null,
            "property_id": 1,
            "is_360": false,
            "deleted_at": null,
            "file_size": 36350,
            "duration": null
        },
        "fileShares": [
            {
                "id": 18,
                "linkId": "eyJpdiI6ImtFTE1SYUp2S2FZbVVXS1dHV3pWUEE9PSIsInZhbHVlIjoiWkRvOXBONGpnV2JJXC8ycmpXYmJJYm5sZTRqZnV4Tm9DQ1BJRXBMSHF0dkIwK1ROZysyT3ZkK1owcFpQcVlSZDUxc2w2NXZrRmU1SXpDNGUwU2c2ejdRPT0iLCJtYWMiOiIwZjYxN2FmMmRjMTI0NDcyNjAzOGM4YTViOGI3YTRkMTI4OTg4YTViNDhlMmRhYzkyN2U3NmYyMWUyYWQ4NzIyIn0=",
                "alias": "",
                "inspectionId": null,
                "attachmentId": 56,
                "propertyId": 1,
                "firstAccessedAt": null,
                "lastAccessedAt": null
            },
            {
                "id": 17,
                "linkId": "eyJpdiI6IjVNRmJDVnE1aGpkejlXNjFSbVZRWFE9PSIsInZhbHVlIjoiN1l1Qnp2OVF4R0tlYm5jeXlhdUk1VXZ2UlZoaWVIZml5SHgyRGh2eFwvd3F5U1NybUNacGZvZVwvOGFmOUhpUkdkWm52MUxDKzM5NlF6aWJRSERZdlVtZz09IiwibWFjIjoiYTExNDRiYmM1MjBlNDRkMjhkZjVmZmM2YTVkNWUxYzBmYzEwYTM5Zjc4OTZkYTg3N2UxY2M4ZmFiOTVjNTYyOSJ9",
                "alias": "For Emily",
                "inspectionId": null,
                "attachmentId": 56,
                "propertyId": 1,
                "firstAccessedAt": null,
                "lastAccessedAt": null
            }
        ]
    }
]

This endpoint takes a GET and returns all of a properties attachments alongside any file shares that exist for that attachment.

Path Parameters

Field Type Description
propertyId string The ID of the property to reference

Getting all file shares for all of an inspections attachments

GET /file-share/inspection/{inspectionId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

RESPONSE

[
    {
        "attachment": {
            "id": 55,
            "uuid": "18f17aee-0c23-41cd-ae21-dc507041b8f9",
            "type": "file",
            "type_id": 100,
            "url": "https://inventorybase-stage.s3.eu-west-1.amazonaws.com/attachments/1/1/1/ad25b78c-0173-4bae-8cb2-a4a1e667918b.json",
            "thumbnail": "https://inventorybase-stage.s3.eu-west-1.amazonaws.com/attachments/1/1/1/ad25b78c-0173-4bae-8cb2-a4a1e667918b-thumbnail.json",
            "description": null,
            "taken_at": null,
            "metadata": {
                "360": false,
                "page_count": null,
                "uploaded_by_tenant": false,
                "hide_on_report": false,
                "shown_on_report": false,
                "document_name": null
            },
            "room_id": null,
            "item_id": null,
            "previous_attachment_ids": [],
            "inspection_id": 1,
            "property_id": 1,
            "is_360": false,
            "deleted_at": null,
            "file_size": 591587,
            "duration": null
        },
        "fileShares": [
            {
                "id": 16,
                "linkId": "eyJpdiI6IlwvNngzK2lrR3FqYWdvUENrZUtwNTh3PT0iLCJ2YWx1ZSI6IllcLzJTeEdscU52OUV4ZXU4elwvNDdvMW0wTEhxYkZla2dueWtjZGdIbXlXRFk2YmgxYWR6SitoXC9GYUQ2Rk5ZY1wvYUVpVkRUWmlObVc2MXJPeEFOSk53dz09IiwibWFjIjoiYTk0OTdhMjVmNzViYTU4MmUyZDc5ODQ3ZGY1YTIzZWQwMDhmNmJhYmY4YTZhMmU4YjM4NmFmNjExZWY4NzRjYSJ9",
                "alias": "",
                "inspectionId": 1,
                "attachmentId": 55,
                "propertyId": null,
                "firstAccessedAt": null,
                "lastAccessedAt": null
            },
            {
                "id": 13,
                "linkId": "eyJpdiI6IjB0empvXC8xQ0xBZW0xQWwzU2NncmxBPT0iLCJ2YWx1ZSI6IlpqNUpnNHhBajlTZ2t4MVdzdDN2ZFBSUEt6YjNEWFVuZzYxcVBmNDFPbFl5RTZvMGhMYms0NEZYNU1nQ0E0WWg5UXVXOURtWTVpWjBuRzk4U3ZhQllBPT0iLCJtYWMiOiJiYWMxMDE2ZWNkM2IzYWVkYzJmM2VhNjY0ZDBlYmYzYzRmMjEyNzZkNTU2ODQwMjMxOTdhY2Q4NjMxOTVlMzU3In0=",
                "alias": "For Char",
                "inspectionId": 1,
                "attachmentId": 55,
                "propertyId": null,
                "firstAccessedAt": null,
                "lastAccessedAt": null
            }
        ]
    }
]

This endpoint takes a GET and returns all of an inspections attachments alongside any file shares that exist for that attachment.

Path Parameters

Field Type Description
inspectionId string The ID of the inspection to reference

Clients

Clients are users of the system that may login and perform basic functions such as booking inspections and accessing completed reports. They may only access properties that have been assigned to them, and reports for those properties.

The Client object

{
    "id": 3,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "company": "Radweb Ltd",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "website": "example.com",
    "notes": "Robb's a real stand up guy - ask for him by name when calling Radweb Ltd",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    },
    "email_notifications": true,
    "send_login_details": true
}
Field Type Description
id int Unique identifier for the Client
name string The Clients's full name
telephone string The Client's telephone number
mobile string The Client's mobile telephone number
company string The Client's company name
website string The Client's company website
address Address The Client's address
line1 string Address Line 1 (e.g. the house number & street)
line2 string / null Address Line 2
city string
county string
postcode string
country string
email_notifications boolean Whether the client receives email notifications about events involving their properties
send_login_details boolean Whether to email the client their login credentials. If false their credentials will be sent to the account owner
notes string Notes about the client

List all clients

Request
GET /clients HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "pagination": {
        "perPage": 10,
        "currentPage": 1,
        "totalPages": 1,
        "totalRecords": 1
    },
    "links": {
        "first": "https://api.inventorybase.com/clients?page=1",
        "prev": null,
        "self": "https://api.inventorybase.com/clients?page=1",
        "next": null,
        "last": "https://api.inventorybase.com/clients?page=1"
    },
    "data": [
        {
            "id": 3,
            "name": "Robb Lewis",
            "email": "example@radweb.co.uk",
            "company": "Radweb Ltd",
            "telephone": "01234555666",
            "mobile": "07777555666",
            "website": "example.com",
            "notes": "Robb's a real stand up guy - ask for him by name when calling Radweb Ltd",
            "address": {
                "line1": "123 Example Lane",
                "line2": null,
                "city": "Londsville",
                "county": null,
                "postcode": "HL3 4IB"
            },
            "email_notifications": true
        }
    ]
}

Retrieve a paginated list of all the account's Clients.

Query Parameters

Field Type Description
name string Perform a search on the client name/company
email string Find a specific client

Find Client by ID

Request
GET /clients/{clientId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "id": 3,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "company": "Radweb Ltd",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "website": "example.com",
    "notes": "Robb's a real stand up guy - ask for him by name when calling Radweb Ltd",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    },
    "email_notifications": true
}

Retrieve a single client by ID.

Create a Client

Request

POST /clients HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "company": "Radweb Ltd",
    "telephone": "01234555666",
    "website": "example.com",
    "notes": "Robb's a real stand up guy - ask for him by name when calling Radweb Ltd",
    "address": {
        "line1": "123 Example Lane",
        "city": "Londsville",
        "postcode": "HL3 4IB"
    }
}

Response

{
    "id": 3,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "company": "Radweb Ltd",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "website": "example.com",
    "notes": "Robb's a real stand up guy - ask for him by name when calling Radweb Ltd",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    },
    "email_notifications": true
}

Perform a POST request to the /clients endpoint.

Input

Field Type Description
name string The Client's full name Required
email string The Client's email address Required
telephone string The Client's telephone number
mobile string The Client's mobile phone number
company string The Client's company name
website string The Client's company website
notes string Notes about the client
address object The Client's primary address. Typically their office.
line1 string Required
line2 string?
city string Required
county string?
postcode string Required
send_login_details boolean Determine whether to send login details to the newly created client if true, or the account owner if false. Defaults to true
email_notifications boolean Determine whether the client should receive email notifications regarding inspections for their properties. Defaults to true
ignore_welcome_mailer boolean Completely omit the initial welcome mailer to a client or related account owner containing their login information. If specified as true, send_login_details will have no effect because no email will be sent to either party

Update a Client

Request

PUT /clients/{clientId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "company": "Radweb Ltd",
    "telephone": "01234555666",
    "website": "example.com",
    "notes": "Robb's a real stand up guy - ask for him by name when calling Radweb Ltd",
    "address": {
        "line1": "123 Example Lane",
        "city": "Londsville",
        "postcode": "HL3 4IB"
    }
}

Response

{
    "id": 3,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "company": "Radweb Ltd",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "website": "example.com",
    "notes": "Robb's a real stand up guy - ask for him by name when calling Radweb Ltd",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    },
    "email_notifications": true
}

Perform a PUT request to the /clients/{clientId} endpoint.

Field Type Description
name string The Client's full name
email string The Client's email address
telephone string The Client's telephone number
mobile string The Client's mobile phone number
company string The Client's company name
website string The Client's company website
notes string Notes about the client
address object The Client's primary address. Typically their office.
line1 string
line2 string?
city string
county string?
postcode string

Errors

HTTP Status Description
409 Conflict The email address already exists.

Staff

Staff members are users of the system that may login and perform functions such as booking inspections, managing settings, conducting reports, etc.

The Staff object

{
    "id": 3,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "role": 2,
    "title": "Mr",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    }
}
Field Type Description
id int Unique identifier for the Staff member
name string The Staff member's full name
email string The Staff member's email address
role enum The Staff member's role permissions. See Roles for more information.
title string The Staff member's title
telephone string The Staff member's telephone number
mobile string The Staff member's mobile number
address Address The Staff member's address
line1 string Address Line 1 (e.g. the house number & street)
line2 string / null Address Line 2
city string
county string
postcode string
country string

List all staff members

Request
GET /staff HTTP/1/1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "pagination": {
        "perPage": 10,
        "currentPage": 1,
        "totalPages": 1,
        "totalRecords": 1
    },
    "links": {
        "first": "https://api.inventorybase.com/staff?page=1",
        "prev": null,
        "self": "https://api.inventorybase.com/staff?page=1",
        "next": null,
        "last": "https://api.inventorybase.com/staff?page=1"
    },
    "data": [
        {
            "id": 3,
            "name": "Robb Lewis",
            "email": "example@radweb.co.uk",
            "role": 2,
            "title": "Mr",
            "telephone": "01234555666",
            "mobile": "07777555666",
            "address": {
                "line1": "123 Example Lane",
                "line2": null,
                "city": "Londsville",
                "county": null,
                "postcode": "HL3 4IB"
            }
        }
    ]
}

Retrieve a paginated list of all the account's Staff members.

Query Parameters

Field Type Description
role int[] Filter for Staff members assigned a specific role
name string Perform a search on Staff members by name
email string Perform a search on Staff members by email

Find Staff member by ID

Request
GET /staff/{clientId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "id": 3,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "role": 2,
    "title": "Mr",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    }
}

Retrieve a single staff member by ID.

Create a Staff member

Request
POST /staff HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "role": 2,
    "title": "Mr",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    }
}
Response
{
    "id": 1,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "role": 2,
    "title": "Mr",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    }
}

Perform a POST request to the /staff endpoint

Input

Field Type Description
name string The Staff member's full name Required
email string The Staff member's email address Required
role enum The Staff member's role permissions. See Roles for more information. Required
title string The Staff member's title
telephone string The Staff member's telephone number
mobile string The Staff member's mobile number
address Address The Staff member's address
line1 string Address Line 1 (e.g. the house number & street)
line2 string / null Address Line 2
city string
county string
postcode string
country string

Update a staff member

Request
PUT /staff/{staffId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "role": 2,
    "title": "Mr",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "address": {
        "line1": "123 Example Lane",
        "city": "Londsville",
        "postcode": "HL3 4IB"
    }
}
Response
{
    "id": 1,
    "name": "Robb Lewis",
    "email": "example@radweb.co.uk",
    "role": 2,
    "title": "Mr",
    "telephone": "01234555666",
    "mobile": "07777555666",
    "address": {
        "line1": "123 Example Lane",
        "line2": null,
        "city": "Londsville",
        "county": null,
        "postcode": "HL3 4IB"
    }
}

Perform a PUT request to the /staff/{staffId} endpoint.

Field Type Description
name string The Staff member's full name
email string The Staff member's email address
role enum The Staff member's role permissions. See Roles for more information.
title string The Staff member's title
telephone string The Staff member's telephone number
mobile string The Staff member's mobile number
address Address The Staff member's address
line1 string Address Line 1 (e.g. the house number & street)
line2 string / null Address Line 2
city string
county string
postcode string
country string

Errors

HTTP Status Description
409 Conflict The email address already exists.

Templates

Templates are pre-configured forms with a list of rooms/blocks and items in a particular order and format(s).

The Template object

{
    "id": 1,
    "name": "Inventory Report - 3 Bedrooms",
    "inspection_type": 1,
    "property_details": {
        "furnished": "Unfurnished",
        "type": "House",
        "no_of_beds": 3,
        "no_of_baths": 1
    }
}
Field Type Description
id int Unique identifier for the object
name string The name of the Template
inspection_type object | null
id int Numerical representation of the inspection type
name string Textual representation of the inspection type

The possible Inspection types are detailed above.

property_details object
furnished string | null One of "Unfurnished", "Part Furnished", "Fully Furnished"
type string | null Type of property this is, e.g. "House", "Apartment", "Castle" etc.
no_of_beds int Number of Bedrooms
no_of_baths int Number of Bathrooms

The Template Report object

This is identical to the Inspection Report object.

Retrieve Inspection Report

Request
GET /templates/{templateId}/report HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN
Response
{
    "rooms": [],
    "attachments": {}
}

This response is identical to the Inspection Report object.

Loading an Template

Request

PUT /inspections/{inspectionId}/templates/{templateId} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer ACCESS_TOKEN

{
    "mode": "append"
}

Response

{
    "rooms": [],
    "attachments": {}
}

Perform a PUT request to the Inspection's Template load endpoint. This will copy the Rooms and Items from the Template onto the Inspection's Report.

The API will respond with the updated Report object.

There are two "modes" when loading a Template. The append mode will add the copied Rooms after any existing Rooms on the Report. This mode is the default, so does not need to be specified in the request.

The reset mode will remove all existing Rooms from the Report, then add the copied Rooms.

Input

Field Input Description
mode string? The mode of the copy - either append or reset

Webhooks

Get notified when interesting events happen within InventoryBase. This allows your system to act when, for example, a Clerk is assigned to an Inspection, or an Inspection is Signed etc.

Important Webhook Details

When you register a webhook callback, we will notify you of every event which occurs. It is up to your application to decide which webhook events to act on, and which to ignore.

Your webhook handler must respond with a 200 status code within 3 seconds. Any non-200 status code will be treated as a failure, and will be retried. Any timeouts (over 3 seconds) will be treated as a failure, and will be retried.

The body of your responses will be ignored.

Any failed webhook deliveries will be retried a number of times over several hours.

If requests to your system consistently fail over a period of time, your webhook listener will be automatically disabled.

We store & log all webhook deliveries to allow you to debug any delivery failures. We're currently working on providing external access to this system.

The Webhook Payload

Example JSON Payload

{
  "event": "inspection.clerk.assigned",
  "data": {
    // some data will be here
  }
}

Example XML Payload

<?xml version="1.0" encoding="UTF-8"?>
<json:object xmlns:json="http://www.ibm.com/xmlns/prod/2009/jsonx" xsi:schemaLocation="http://www.datapower.com/schemas/json jsonx.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <json:string name="event">inspection.clerk.assigned</json:string>
 <json:object name="data">
   <!-- some data will be here -->
 </json:object>
</json:object>

Webhooks will be sent as a POST request encoded as either JSON or XML (you pick a format when registering a listener).

Each payload will contain an event field containing the name of the event, and a data field which contains the data specific to that webhook event.

The Webhook Signature

Example PHP

$secret = 'the shared secret you provided inventorybase';
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$body = file_get_contents('php://input');

$signature === hash_hmac('sha256', $body, $secret);

Example Node JS

var crypto = require('crypto')
var secret = 'the shared secret your provided inventorybase'
var signature = 'get the X-Webhook-Signature header'
var body = 'get the request body'

signature ===
    crypto
        .createHmac('sha256', secret)
        .update(body)
        .digest('hex')

It's important that you verify each webhook sent to you to ensure it was sent from InventoryBase, and isn't from a malicious third party.

When you register a webhook listener, you provide us with a secret.

For every webhook we send you, we'll include an X-Webhook-Signature header. The value of this will be a SHA256 HMAC (represented as lowercase hexadecimal) of the webhook's body using the secret key you provided to us.

Construct your own signature by creating a SHA256 HMAC of the full request body (the raw incoming JSON/XML body) using the secret. If the signature you constructed does not match the signature provided in the X-Webhook-Signature header, abort the request.

You can find a collection of examples of this process in several different languages here. Please note our hashes are encoded as lowercase hexadecimal/hexits, not base64.

Register a Webhooks Listener

As an application developer, you can create a Webhook listener for the user's account. Send a POST to

POST /webhooks HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer OAUTH_ACCESS_TOKEN

{
    "name": "Descriptive Name",
    "url": "https://foo.let/receive-webhook/inventorybase",
    "secret": "OF9lcSaA9JemFGzF9nSXuFmuQVVSNimBXvWao7KxQZUwGtbPR4NlJaQA5LsS4Pt1",
    "format": "application/json"
}

Input

Field Type Description
name string A descriptive name for your system (will be shown in UI to user) Required
url string The URL we should POST the webhook payload to Required
secret string A shared secret we will use to create a verification signature for each request; must be at least 32 characters Required
format string The format you wish to receive payloads in, either application/json or application/xml Required

Delete a Webhook Listener

When developing your application you may need to delete Webhook listeners. Send a DELETE request to.

DELETE /webhooks/{webhook_id} HTTP/1.1
Host: https://api.inventorybase.com
Authorization: Bearer OAUTH_ACCESS_TOKEN

Webhook Events

The following events are sent as webhooks to you. The data listed will appear inside the data field of the webhook payload (detailed above).

{
  "event": "inspection.created",
  "data": {
    "inspection_id": 1,
    "actor": {
      // ...
    },
    "inspection": {
      // ...
    }
  }
}

inspection.created

Field Object Details
inspection_id int The ID of the inspection that was created
actor Person The person who created the Inspection
inspection Inspection The Inspection that was created 
{
  "event": "inspection.updated",
  "data": {
    "inspection_id": 1,
    "actor": {
      // ...
    },
    "inspection": {
      // ...
    }
  },
}

inspection.updated

Field Object Details
inspection_id int The ID of the inspection that was updated
actor Person The person who updated the Inspection
inspection Inspection The Inspection that was updated 
{
  "event": "inspection.updated.title",
  "data": {
    "inspection_id": 1,
    "actor": {
      // ...
    },
    "from": "Inventory",
    "to": "Inventory and Schedule of Condition",
  }
}

inspection.updated.title

Field Object Details
inspection_id int The ID of the inspection that was updated
actor Person The person who updated the Inspection
from string The previous Inspection title
to string The new Inspection title 
{
  "event": "inspection.updated.date",
  "data": {
    "inspection_id": 1,
    "actor": {
      // ...
    },
    "from": "2014-10-17T08:30:00",
    "to": "2014-10-18T12:30:00",
  }
}

inspection.updated.date

Field Object Details
inspection_id int The ID of the inspection that was updated
actor Person The person who updated the Inspection
from iso 8601 Date the Inspection was scheduled to be carried out on
to iso 8601 Date the Inspection is scheduled to be carried out on 
{
  "event": "inspection.updated.clerk",
  "data": {
    "inspection_id": 1,
    "actor": {
      // ...
    },
    "from": {
        "id": 14,
        "name": "Dan Harper",
        "is_manager": true
      },
    "to": {
        "id": 15,
        "name": "Robb lewis",
        "is_manager": false
      },
  }
}

inspection.updated.clerk

Field Object Details
inspection_id int The ID of the inspection that was updated
actor Person The person who updated the Inspection
clerk object | null The previous Clerk assigned to this Inspection
id int Unique identifier for the User/Clerk
name string The Clerk's full name
is_manager bool Is the Clerk part of Management (has more priviledges)
clerk object | null The new Clerk assigned to this Inspection
id int Unique identifier for the User/Clerk
name string The Clerk's full name
is_manager bool Is the Clerk part of Management (has more priviledges) 
{
  "event": "inspection.updated.type",
  "data": {
    "inspection_id": 1,
    "actor": {
      // ...
    },
    "from": {
      "id": 1,
      "name": "Inventory"
    },
    "to": {
      "id": 2,
      "name": "Check In"
    },
  }
}

inspection.updated.type

Field Object Details
inspection_id int The ID of the inspection that was updated
actor Person The person who updated the Inspection
from object The previous inspection type
id int Numerical representation of the inspection type
name string Textual representation of the inspection type
to object The new inspection type
id int Numerical representation of the inspection type
name string Textual representation of the inspection type

The possible Inspection types are detailed above.

{
  "event": "inspection.submitted_for_review",
  "data": {
    "inspection": {
      // ...
    },
    "actor": {
      // ...
    }
  }
}

inspection.submitted_for_review

Field Object Details
inspection Inspection The Inspection that was submitted for review
actor Person The person who submitted the Inspection for review 
{
  "event": "inspection.completed",
  "data": {
    "inspection": {
      // ...
    },
    "actor": {
      // ...
    }
  }
}

inspection.completed

Field Object Details
inspection Inspection The Inspection that was completed
actor Person The person who completed the Inspection 
{
  "event": "inspection.reopened",
  "data": {
    "inspection": {
      // ...
    },
    "actor": {
      // ...
    }
  }
}

inspection.reopened

Field Object Details
inspection Inspection The Inspection that was completed
actor Person The person who completed the Inspection 
{
  "event": "inspection.cancelled",
  "data": {
    "inspection": {
      // ...
    },
    "actor": {
      // ...
    }
  }
}

inspection.cancelled

Field Object Details
inspection Inspection The Inspection that was cancelled
actor Person The person who cancelled the Inspection 
{
  "event": "inspection.closed",
  "data": {
    "inspection": {
      // ...
    },
    "actor": {
      // ...
    }
  }
}

inspection.closed

Field Object Details
inspection Inspection The Inspection that was closed
actor Person The person who closed the Inspection 
{
  "event": "pdf.generated",
  "data": {
    "inspection": {
      // ...
    },
    "pdf": {
      // ...
    }
  }
}

pdf.generated

Field Object Details
inspection Inspection The Inspection
pdf PDF The PDF 
{
  "event": "property.updated",
  "data": {
    "property_id": 1,
    "actor": {
      // ...
    },
    "property": {
        // ...
    }
  },
}

property.updated

Field Object Details
property_id int The ID of the property that was updated
actor Person The person who updated the Inspection
property Property The property that was updated 
{
  "event": "property.deleted",
  "data": {
    "property_id": 1,
    "actor": {
      // ...
    },
  },
}

property.deleted

Field Object Details
property_id int The ID of the property that was deleted
actor Person The person who updated the Inspection 
{
  "event": "property.created",
  "data": {
    "property": {
      // ...
    },
    "actor": {
      // ...
    },
  },
}

property.created

Field Object Details
property Property The property that was created
actor Person The person who updated the Property 
{
  "event": "client.updated",
  "data": {
    "client_id": 1,
    "actor": {
      // ...
    },
    "client" : {
        // ...
    }
  },
}

client.updated

Field Object Details
client_id int The ID of the client that was updated
actor Person The person who updated the Inspection
client Client The client that was updated 
{
  "event": "client.deleted",
  "data": {
    "client_id": 1,
    "actor": {
      // ...
    },
  },
}

client.deleted

Field Object Details
client_id int The ID of the client that was deleted
actor Person The person who updated the Inspection 
{
  "event": "client.created",
  "data": {
    "client": {
      // ...
    },
    "actor": {
      // ...
    },
  },
}

client.created

Field Object Details
client Client The client that was created
actor Person The person who updated the Client

actionReport.created

Field Object Details
report Action Report The action report that was created 
{
  "event": "actionReport.created",
  "data": {
    "report": {
      // ...
    }
  }
}

Registration

You can register new user accounts via the API. Your application will be granted all OAuth scopes on any accounts that you create this way.

Register

Request

POST /register HTTP/1.1
Host: https://api.inventorybase.com
x-client-id: OAUTH_CLIENT_ID
x-request-hash: REQUEST_HMAC
Content-Type: application/json

{
  "name": "Johaniss Scutsenberg",
  "email": "jscuts@example.com",
  "company": "Scuts Inventories"
}

JSON Response

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer"
}

Perform a POST request to the /register endpoint and receive an access token in the same format as the authentication endpoint

Headers

Header Description
x-client-id Your application's OAuth client ID
x-request-hash A HMAC of the request body

The request hash must be a SHA-256 encoded HMAC (encoded as lowercase hexidecimal) of the raw request body. It should be signed with your OAuth client secret, and is used to authenticate and verify the request. See this guide for examples in a wide range of commonly used languages.

Input

Field Type Description
name string The name of the user being created Required
email string The email the user will log in with Required
company string The company associated with the user Required

SAML 2.0 - SSO

InventoryBase supports SSO via Security Assertion Markup Language 2.0. SSO is only available to Whitelabel customers using a custom domain.

We support the NameID format urn:oasis:names:tc:SAML:2.0:nameid-format:persistent which should contain a unique identifier for the user.

Our Entity ID is https://my.inventorybase.com/sp.

The SAML Service Provider endpoints will use your Whitelabel domain that is configured for use with InventoryBase. The urls are as follows

Description URL
Service Provider Initiated Login Flow /sso/saml/login
Service Provider Metadata /sso/saml/metadata
Assertion Consumer Service /sso/saml/assertion-consumer-service
Service Provider Logout Service /sso/saml/single-logout-service

Available Attributes

When configuring your Identity Provider, these are the attributes you may use.

Attribute Value Instruction
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name Full name of the user Required
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Email address of the user Required
https://my.inventorybase.com/2022/identity/claims/role Role of the user. See Roles for more information. Default Clerk Optional

SCIM - User Provisioning

InventoryBase supports user provisioning via System for Cross-domain Identity Management (SCIM v2.0).

Our SCIM API uses oauthbearertoken authentication. You may generate a token in the dev centre

The endpoint for SCIM is available at https://api.inventorybase.com/scim

Our user schema is as follows. Role may be one of the following Admin, Manager, Clerk, Typist.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:inventorybase:2.0:user"
    ],
    "id": 100,
    "userName": "bob@example.com",
    "name": {
        "givenName": "",
        "familyName": "",
        "formatted": "Bob Inventories"
    },
    "urn:ietf:params:scim:schemas:extension:inventorybase:2.0:user": {
        "role": "Manager"
    }
}

Misc Objects

The PDF Object

Several "types" of PDF can be generated for a given report. We currently have 3 types, however additional ones can be added at any time, so ensure your system will gracefully handle new types.

{
    "type": "FULL",
    "url": "https://s3.amazonaws.com/...."
}
Field Type Description
type "FULL" | "CHANGES" | "ACTIONS" The type of PDF which was generated
url string The URL to the PDF

The Person object

Usually, you'll receive a Clerk or a Client object from the API. However in places you'll receive a more general "Person"/"Actor" object. You'll see this largely within the system's webhooks to define who caused a certain event to occur.

{
    "id": 1,
    "name": "Dan Harper",
    "company": "Radweb",
    "role": 2
}
Field Type Description
id int Unique identifier for the object
name string User's name
company string | null User's company name (if set)
role int User's role

Roles

ID Description
2 Account Owner
3 Manager
4 Clerk
5 Client
7 Typist
10 Admin Manager

Changelog object

A Changelog object can consist of the following keys.

clerk

{
  "clerk": {
    "from": {
        "id": 14,
        "name": "Dan Harper",
        "is_manager": true
      },
    "to": {
        "id": 15,
        "name": "Robb lewis",
        "is_manager": false
      },
  }
}
Field Object Details
from object | null The previous Clerk assigned to this Inspection
id int Unique identifier for the User/Clerk
name string The Clerk's full name
is_manager bool Is the Clerk part of Management (has more priviledges)
to object | null The new Clerk assigned to this Inspection
id int Unique identifier for the User/Clerk
name string The Clerk's full name
is_manager bool Is the Clerk part of Management (has more priviledges)

type

{
  "type": {
    "from": {
      "id": 1,
      "name": "Inventory"
    },
    "to": {
      "id": 2,
      "name": "Check In"
    },
  }
}
Field Object Details
from object The previous inspection type
id int Numerical representation of the inspection type
name string Textual representation of the inspection type
to object The new inspection type
id int Numerical representation of the inspection type
name string Textual representation of the inspection type

conduct_date

{
  "conduct_date": {
    "from": "2014-10-17T08:30:00",
    "to": "2014-10-18T12:30:00",
  }
}
Field Object Details
from iso 8601 Date the Inspection was scheduled to be carried out on
to iso 8601 Date the Inspection is scheduled to be carried out on

cover_image

{
  "cover_image": {
    "from": {
      "id": 2,
      "url": "http://path/to/image.jpg"
    },
    "to": {
      "id": 3,
      "url": "http://path/to/new_image.jpg"
    }
  }
}
Field Object Details
from object | null The previous Inspection cover image
id int Numerical representation of the Cover Image attachment
url string The URL of the Cover Image
to object | null The new Inspection cover image
id int Numerical representation of the Cover Image attachment
url string The URL of the Cover Image

title

{
  "title": {
    "from": "Inventory",
    "to": "Inventory and Schedule of Condition",
  }
}
Field Object Details
from string The previous Inspection title
to string The new Inspection title

ref

{
  "ref": {
    "from": "ABC123",
    "to": "DEF123",
  }
}
Field Object Details
from string | null The previous Inspection reference
to string | null The new Inspection reference

location_of_keys

{
  "location_of_keys": {
    "from": "With Agent",
    "to": "With Tenant",
  }
}
Field Object Details
from string The previous location of the keys
to string The new location of the keys

internal_notes

{
  "internal_notes": {
    "from": "Please contact tenant by tomorrow.",
    "to": "Tenant has been contacted",
  }
}
Field Object Details
from string | null The previous internal notes
to string | null The new internal notes

client_notes

{
  "client_notes": {
    "from": "Please let me know when this can be done",
    "to": "I am not available on wednesday next week",
  }
}
Field Object Details
from string | null The previous client notes
to string | null The new client notes

price

{
  "price": {
    "from": "100.00",
    "to": "120.00",
  }
}
Field Object Details
from string The previous Inspection price
to string The new Inspection price

additional

{
  "additional": {
    "from": "10.00",
    "to": "15.00",
  }
}
Field Object Details
from string The previous Inspection additional price
to string The new Inspection additional price

margin

{
  "margin": {
    "from": "20.00",
    "to": "22.00",
  }
}
Field Object Details
from string The previous Inspection margin
to string The new Inspection margin

time_to_complete

{
  "time_to_complete": {
    "from": "PT1H20M",
    "to": "PT2H30M",
  }
}
Field Object Details
from iso 8601 duration | null The previous Inspection time to complete
to iso 8601 duration | null The new Inspection time to complete

Concepts

Arrayables

When a query parameter has an arrayable type, e.g. int[] or string[], many parameters may be specified, effectively resulting in an OR query.

As a practical example, if the state_id field has type int[] you may use either:

Dates

All dates on the API are in UTC, and must be provided as UTC. They're displayed in the standard ISO 8601 format. For example, December 25th 2014 at 2:25PM is 2014-12-25T14:24:00.

This format also allows us to intelligently parse intervals, and we use this for querying entities across a range of dates. Let's say you need to query all Inspections whose conduct_date is within the next two weeks: P2W.

Pagination

Example Paginated Response
{
    "pagination": {
        "perPage": 10,
        "currentPage": 1,
        "totalPages": 1,
        "totalRecords": 0
    },
    "links": {
        "first": "https://api.inventorybase.com/inspections?page=1",
        "prev": null,
        "self": "https://api.inventorybase.com/inspections?page=1",
        "next": null,
        "last": "https://api.inventorybase.com/inspections?page=1"
    },
    "data": []
}

The majority of our "list" endpoints are paginated and are wrapped in a "pagination envelope" defining the details of the pagination.

Field Type Description
pagination object
perPage int The number of results displayed per page
currentPage int The number of the current requested page
totalPages int The total number of pages for the request
totalRecords int The total number of records for the request
links object
first string URL of the first page for the request
prev string | null URL of the previous page for the request, if possible
self string URL of the current page
next string | null URL of the next page for the request, if possible
last string URL of the last page for the quest
data array Array of the requested objects

Validation

Example Validation Failure Response
{
    "errors": {
        "line1": ["The line1 field must be a string"],
        "city": ["The city field is required"],
        "type": ["The selected type is not valid"]
    }
}

All validation failure responses will have a status code of 422 (Unprocessable Entity). Errors are grouped by the input name and may have multiple error messages.

Rate Limiter

We limit requests to 60 per minute. This means you can make 60 requests in 5 seconds, and then wait 55 seconds for your limit to reset, or you could make 1 request per second continuously and never hit the rate limiter.

Every response will include the following two headers which contain information about your current rate limit usage

If you use all your requests in the timeframe you'll receive a 429 HTTP Status in the response. This response will include 2 further headers

Configuration

Entity Constants

This endpoint returns all the constants used by the system. These constants are used in requests to specify things like property, contact, and inspection types.

Request

GET /entity-constants

Response Example

{
    "types": [
        {
            "id": 0,
            "title": "Apartment",
            "category": 0
        }
    ],
    "furnishings": [
        {
            "id": 0,
            "title": "Unfurnished"
        }
    ],
    "detachments": [
        {
            "id": 0,
            "title": "Detached"
        }
    ],
    "contactTypes": [
        {
            "id": 1,
            "title": "Tenant"
        }
    ],
    "locationOfKeys": [
        {
            "id": 1,
            "title": "With Agent"
        }
    ],
    "returnKeys": [
        {
            "id": 1,
            "title": "Return from where collected"
        }
    ],
    "actionResponsibilities": [
        {
            "id": 1,
            "title": "Tenant"
        }
    ]
}