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 InventoryBase > Integrations > Create 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
staff.read List Staff users
webhooks.read List Registered webhooks
webhooks.write Manage Webhooks

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_COMMA_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 comma-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://api.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

{
  "access_token": "THE_ACCESS_TOKEN",
  "token_type": "bearer"
}

XML Response

<oauth>
  <access_token>THE_ACCESS_TOKEN</access_token>
  <token_type>bearer</token_type>
</oauth>

Response

Field Description
access_token The access token
token_type Will always be bearer

Our Access Tokens do not expire unless explicitly revoked by the user or by InventoryBase.

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,
  "notes": "Some notes",
  "activated": true,
  "client": {
    "id": 4,
    "name": "Ali Smith"
  }
}
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
activated bool Whether the Property is "activated" or not (users can disable them to hide old properties from their list)
no_of_garages int Number of Garages
client object / null The Client the Property belongs to
id int Client identifier
name string Client's full name

List all properties

Request
GET /properties HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY
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,
      "notes": "Some notes",
      "activated": true,
      "client": {
        "id": 4,
        "name": "Ali Smith"
      }
    }
  ]
}

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
X-API-Key: USERS_API_KEY
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,
  "notes": "Some notes",
  "activated": true,
  "client": {
    "id": 4,
    "name": "Ali Smith"
  }
}

Retrieve a single property by it's id.

Creating a Property

Request

POST /properties HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY
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"
}

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,
  "notes": "Foo bar baz qux",
  "activated": true,
  "client": null
}

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?
notes string?

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 Team endpoint to find a clerk's ID.

Inspection States

Code Name Description
100 "Pending" Inspection appointment added
200 "Assigned" Inspection assigned to team 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
3 "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,
    "notes": "Some notes",
    "activated": true,
    "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",
  "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",
  "updated_at": "2014-10-17T06:36:02",
  "completed_at": null,
  "closed_at": null
}
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
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
conduct_date iso 8601 | null Date the Inspection is scheduled to be carried out on
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

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

List all inspections

Request
GET /inspections HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY
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,
        "notes": "Some notes",
        "activated": true,
        "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",
      "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
X-API-Key: USERS_API_KEY
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 Actions

Request
GET /inspections/{inspectionId}/report/actions HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY
Response
[]

Access all Action objects for each item within every room for a given report.

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
X-API-Key: USERS_API_KEY
Content-Type: application/json
{
  "property": {
    "id": 3
  },
  "type": {
    "id": 1,
  },
  "location_of_keys": "With Agent",
  "conduct_date": "2015-06-01",
  "time_to_complete": "PT1H20M",
  "clerk": {
    "id": 1
  },
  "notes": {
    "internal": "Created via API"
  }
}

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,
    "notes": "Foo bar baz qux",
    "activated": true,
    "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",
  "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 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; 6 = Check Out; etc.)
title string?
location_of_keys string Required
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

Copying an Inspection Report from another Property

PUT /inspections/:inspectionId/copy-from-property/:sourcePropertyId HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

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

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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

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
X-API-Key: USERS_API_KEY

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

Copying a Room

Request - Copying to existing Room

PUT /inspections/:inspectionId/rooms/:roomId/copy HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

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

Response

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

Request - Copying to a new Room

PUT /inspections/:inspectionId/rooms/:roomId/copy HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

{
  "room": {
    "name": "Office COPY"
  }
}

Response

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

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

If specifying a name, a new Room will be created with the Items 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 Room's Items will be copied to the existing Room with that id.

Additionally, if copying to an existing Room, a list of overwrite_ids can be specified. Any Items with an id in the overwrite_ids will update the 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_ids array? List of Items to be overwritten in existing Room

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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

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
X-API-Key: USERS_API_KEY

[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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

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.

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
X-API-Key: USERS_API_KEY

Request - Room Endpoint

POST /inspections/:inspectionId/rooms/:roomId/attachments HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

Request - Item Endpoint

POST /inspections/:inspectionId/rooms/:roomId/items/:itemId/attachments HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

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
X-API-Key: USERS_API_KEY

{
  "description": "Foo bar"
}

Request - Room Endpoint

PUT /inspections/:inspectionId/rooms/:roomId/attachments/:attachmentId HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

{
  "description": "Foo bar"
}

Request - Item Endpoint

PUT /inspections/:inspectionId/rooms/:roomId/items/:itemId/attachments/:attachmentId HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

{
  "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
X-API-Key: USERS_API_KEY

Request - Room Endpoint

DELETE /inspections/:inspectionId/rooms/:roomId/attachments HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

Request - Item Endpoint

DELETE /inspections/:inspectionId/rooms/:roomId/items/:itemId/attachments HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY

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.

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
}
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 Wether the client recieves email notifications about events involving their properties
notes string Notes about the client

List all clients

Request
GET /clients HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY
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.

Create a Client

Request

POST /clients HTTP/1.1
Host: https://api.inventorybase.com
X-API-Key: USERS_API_KEY
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
telephone 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 accout owner if false. Defaults to true
email_notifications boolean Determine whether the client should recieve 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

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
X-API-Key: USERS_API_KEY
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
X-API-Key: USERS_API_KEY
{
  "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

Under Development

We currently only expose a few events as webhooks. If there's something you need which we don't yet include, please contact us.

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

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": {
      // ...
    },
    "actor": {
      // ...
    }
  }
}

inspection.created

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

inspection.updated

Field Object Details
inspection Inspection The Inspection that was updated
actor Person The person who updated the Inspection
changes Changelog The Inspection attributes that have changed
{
  "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.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.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

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

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
1 System (Reserved, Unused)
2 Account Owner
3 Manager
4 Clerk
5 Client
6 Tenant
7 Typist

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.