OTISS provides a RESTful API to allow Arboricultural Consultants to read, create and update their table of Clients. This API is typically used to link OTISS to your CRM or Accounts package. When you add new clients, then they can be automatically added into OTISS.
This is a new feature within OTISS and is constantly developing to suit our users’ requirements. Please contact us if you have suggestions for features or options that you would like to see.
You need to pay an extra DATA API subscription to enable this feature for each account. When this option is enabled, the Account Settings-> Account API webpage appears to allow you to create the Security Credentials required.
NB: Within OTISS each Client is a separate ‘Estate’ – so the word Estate is used in the API below.
NB: This API solely looks at the Client/Estate details; a separate API is used to look at the trees and furniture items within each estate – read more…
API Protocol
All access must use HTTPS GET or HTTPS POST requests.
For example: HTTPS GET “https://www.otiss.co.uk/treesurvey/api/estates/table.json?token=R7IkHoyH78mWK5XQMAcH&rows=50&page=1”
or HTTPS POST “https://www.otiss.co.uk/treesurvey/api/estates/table.json” with POST data of “token=R7IkHoyH78mWK5XQMAcH&rows=50&page=1”
All data is returned formatted as JSON.
Security Credentials
All access to the RESTful API is controlled via an alpha-numeric token that must be included with every request, e.g. &token=R7IkHoyH78mWK5XQMAcH. These tokens must be stored securely and not shared with un-authorised users.
The token determines what data can be accessed and in whose name.
| Aspect | Security |
| Account | Only the clients/estates for a specified OTISS account can be accessed via each token. |
| Roles | A token is further restricted to a small set of specified roles – e.g. VIEW, CREATE and/or UPDATE. |
Use the Account Settings-> Account API webpage to create, delete and modify tokens.
- Create new tokens and roles.
- Enable/Disable existing tokens.
- Edit existing tokens to change the token or the roles.
- Delete tokens.
If a token is compromised or suspected of been compromised, then the token can be revoked at any time and a replacement token can be generated.
Client/Estate Table
To access the OTISS Clients table, use HTTPS GET or POST using the URL: https://www.otiss.co.uk/treesurvey/api/estates/table.json
Use the following request parameters.
| Request Parameter | Status | Data Type | Comments |
| token | required | Alpha-numeric String | security credential |
| rows | required | Integer | requested number of rows of data. E.g. 50 rows. |
| page | required | Integer | page number. E.g. 1 = return the first 50 rows, 2= return rows 51..100. |
| filters | optional | URL encoded JSON | specify a simple/complex filter based on the data fields – see below for more information. NB the JSON must be URL encoded. |
The returned JSON data is formatted as {“page”:1,”total”:13,”records”:37,”rows”:[{…},{…},…]}”
| Field Name | Data Type | Comments |
| page | Integer | the requested page number |
| total | Integer | total number of pages of data for the specified #rows |
| records | Integer | total number of rows across all pages |
| rows | Array of Objects | the data rows on this page – i.e. #rows or less. A values of [ ] means that these is no data rows on this page. |
| message | String | error message or null |
The data items for each row is similar to those available when viewing the Manage Clients webpage.
Update Client/Estate Data
The Clients/Estates can be updated using a HTTPS POST operation with the following URL: https://www.otiss.co.uk/treesurvey/api/estates/update.json
Use the following request parameters.
| Request Parameter | Status | Data Type | Comments |
| token | required | Alpha-numeric String | security credential |
| estateId | required | UUID as String | The UUID of the estate to be updated. |
| dataField (mostly the same parameter names as provided in the table) | optional | varies, can be blank/null | The new value for this field. |
The returned JSON data is formatted as {“success”:true|false,”items”:[{…},{…},…]}”
| Field Name | Data Type | Comments |
| success | Boolean | The request succeeded or failed. If false, then no data was update. |
| items | Array of Objects { id: “field”, message: “error” } | Explanation messages are provided for each field when the operation fails. |
Create new Client/Estate Data
A Clients/Estates can be created using a HTTPS POST operation with the following URL: https://www.otiss.co.uk/treesurvey/api/estates/create.json
For example; post data = ‘token=FGh3yiDz61eetkhSH02&estateName=My new Client&surname=Blogs&forename=Fred&telephone1=01234 123 654’
Use the following request parameters.
| Request Parameter | Status | Data Type | Comments |
| token | required | Alpha-numeric String | security credential |
| estateName | required | Alpha-numeric String | Client/Estate name |
| forename | required | Alpha-numeric String | Name of main contact |
| surname | required | Alpha-numeric String | Name of main contact |
| dataField (mostly the same parameter names as provided in the table) | optional | varies, can be blank/null | The new value for this field. |
The returned JSON data is formatted as {“success”:true|false,”items”:[{…},{…},…]}”
| Field Name | Data Type | Comments |
| success | Boolean | The request succeeded or failed. If false, then no data was update. |
| items | Array of Objects { id: “field”, message: “error” } | The new estateId/UUID is returned when the operation succeeds, or Explanation messages are provided for each field when the operation fails. |