location API

Follow

Summary

Requirements

All API calls require a dedicated JSON Web Token (JWT). These are created when a user with a dedicated mobile resource logs in to the application. If you are using the API for programmatic queries, it is best to create a dedicated user for the JWT as this gets reset each time the user logs in.

Endpoint

rest/contact/location

POST

Adds new site data, or updates existing site if a site with a matching reference and client ID currently exists in the system.

File Format Spec

 

List of included fields
Field Name Data Type Mandatory? Description Updatable?
clientRef Text (50) Yes The ref of the client in Oneserve No
locationRef Text (50) Yes A unique reference for the location No
groupId Integer Yes The Location Group ID. Must match one of the pre-configured groups Yes
usageTypeId Integer Yes The Usage Type ID. Must match one of the pre-configured usage types Yes
ignoreUsageTypeOnUpdate Boolean No Determines whether the usage type should be updated if the site exists already in the system Yes
regionId Integer Yes The Region ID. Must match one of the pre-configure regions Yes
typeId Integer Yes The Location Type ID. Must match one of the pre-configured types No
name Text (255) Yes The location name Yes
code Text (20) No The code value for the site Yes
parentLocationRef Text (50) No The reference of the Parent Site. Parent site needs to be under the same client Yes
description Text (2000) No The sites notes field in Oneserve Yes
address1 Text (255) Yes The location address line 1 Yes
address2 Text (255) Yes The location address line 2 Yes
address3 Text (255) No The location address line 3 Yes
address4 Text (255) No The location address line 4 Yes
postCode Text (25) Yes The location post code Yes
statusId Integer Yes 1 - Under Construction
2 - Live
3 - Decommissioned
4 - Void
Yes
deleted true/false Yes If TRUE, archives the site in Oneserve. If FALSE, activates the site in Oneserve Yes
area Text (50) No The location area Yes
considerations Text (1000) No Site considerations Yes
latLongSourceExternal true/false No True will allow the use of latitude and longitude fields otherwise they are ignored, if true and lat long are not included they are set to null
False will use the provided postcode to update lat/long if this is enabled in the system
Yes
latitude BigDecimal No Has to be within UK bounds, 49 - 61 Yes
longitude BigDecimal No Has to be within UK bounds, -8.3 - 2 Yes
attributes Array No An array of attribute values to be passed on site creation. The attribute name must match an attribute currently against the site type in Oneserve Yes
name Text (200) No The name of the attribute to be updated Yes
value Text (1000) No The value to be held against the attribute. This must match the format used by the attribute in Oneserve (e.g. date, date time, lookup) Yes

 

Request Representations

 

Example JSON Payload
{
  "clientRef": "ddhs",
  "locationRef": "abc123",
  "groupId": "23",
  "ignoreUsageTypeOnUpdate": 1,
  "usageTypeId": "34",
  "regionId": "3",
  "typeId": "9",
  "name": "Allen Ave, 12",
  "description": "desc",
  "code": "ABC",
  "parentLocationRef": "abc123",
  "address1": "12 Allen Ave",
  "address2": "Eastleigh",
  "address3": "Oxon",
  "address4": "",
  "postCode": "DF8 89H",
  "statusId": "2",
  "area": "North",
  "considerations": "cat",
  "deleted": true,
  "latLongSourceExternal": true,
  "latitude": 50.01,
  "longitude": 1.1,
  "attributes": [{
          "name": "Number of Windows",
          "value": "5"
      },
      {
          "name": "Colour",
          "value": "Red"
      }
  ]
}

 

Available Response Representations

HTTP Code Description Schema
200 Site(s) Posted siteId: Integer
400 Bad Request Error
401 Unauthorized Error
403 Forbidden Error
404 Address Not Found Error
405 Method Not Allowed Error
415 Unsupported Media Type Error
500 Internal Server Error Error

Example Success Response

{
    "siteId": "1385",
    "result" : "success",
    "result_msg" : ""
}

Troubleshooting

 

401 Unauthorized

Response

401 Unauthorized

Reason

This error occurs if the OS_REST_AUTH_TOKEN has not been provided, has expired, or does not exist in the system

Resolution

Verify your OS_REST_AUTH_TOKEN with support

403 Forbidden

Response

403 Forbidden

Reason

This error indicates that something is blocking your connection to the server

Resolution

Open a ticket with the support team with details of your connection so that your access can be verfied

404 Not Found

Response

404 Not Found

Reason

This error should only occur if the endpoint has been mistyped in some way, which will lead the call to an endpoint that does not exist

Resolution

Verify the endpoint matches the value specified in this article

405 Method Not Allowed

Response

405 Method Not Allowed

Reason

This error will occur if an unacceptable method has been used in the call such as GET or DELETE

Resolution

Ensure that you are using a POST call to this endpoint

415 Unsupported Media Type

Response

415 Unsupported Media Type

Reason

This response is given if data is passed to the endpoint in a format other than application/json

Resolution

Pass your requests as a JSON object with the application/json header

REST0002

Response

{
    "result": "fail",
    "result_msg": "REST0002",
    "result_error_msg": "A JSONObject text must begin with '{' at character..."
}

Reason

This error occurs if you have tried to pass a call that isn't wrapped as a JSON object. For example:

[
    {
        "locationRef": "myref",
        ...
    }
]

Resolution

Ensure that all calls are valid JSON objects following a similar layout to the example call above

Transaction rolled back because it has been marked as rollback-only

Response

{
    "result": "fail",
    "result_msg": "Transaction rolled back because it has been marked as rollback-only"
}

Reason

This is a generic server error which usually indicates that a field is of the wrong type or is overlong, which causes a failure to insert the data into the database

Resolution

Ensure that all fields are filled out according to the field data types listed above

Could not execute statement

Response

{
    "result": "fail",
    "result_msg": "could not execute statement; SQL [n/a]; nested exception is org.hibernate.exception.DataException: could not execute statement"
}

Reason

This is a generic server error which usually indicates that a field is of the wrong type or is overlong, which causes a failure to insert the data into the database

Resolution

Ensure that all fields are filled out according to the field data types listed above

JSONObject "regionId" is not a number

Response

{
    "result": "fail",
    "result_msg": "JSONObject[\"regionId\"] is not a number"
}

Reason

This is caused by a non-integer value being used in the regionId field

Resolution

Ensure that all fields are filled out according to the field data types listed above

JSONObject "statusId" is not a number

Response

{
    "result": "fail",
    "result_msg": "JSONObject[\"statusId\"] is not a number"
}

Reason

This is caused by a non-integer value being used in the statusId field

Resolution

Ensure that all fields are filled out according to the field data types listed above