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/locationContact
POST
Adds new site and contact data, or updates existing data if a site with a matching reference and client ID currently exists in the system.
File Format Spec
Locations Array 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 - VoidYes
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 systemYes
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
Contacts Array Fields
Field Name
Data Type
Mandatory?
Description
Updatable?
clientRef
Text (50
Yes
The ref of the client in Oneserve
No
contactRef
Text (50)
Yes
A unique reference for the contact
No
salutation
Text (50)
Yes
The contact salutation in Oneserve
Yes
forename
Text (80)
Yes
The contact forename
Yes
surname
Text (80)
Yes
The contact surname
Yes
contact1
Text (80)
Yes
Contact 1 details.
Yes
contact1Type
Integer
Yes
Contact 1 type Id. Must match one of the pre-configured types.
Yes
contact2
Text (50)
No
Contact 2 details.
Yes
contact2Type
Integer
No
Contact 2 type Id. Must match one of the pre-configured types.
Yes
contact3
Text (80)
No
Contact 3 details.
Yes
contact3Type
Integer
No
Contact 3 type Id. Must match one of the pre-configured types.
Yes
contact4
Text (80)
No
Contact 4 details.
Yes
contact4Type
Integer
No
Contact 4 type Id. Must match one of the pre-configured types.
Yes
preferredContact
Integer
Yes
Number of the preferred contact: 1 - 4.
Yes
address1
Text (200)
Yes
Address line 1 for the contact
Yes
address2
Text (200)
Yes
Address line 2 for the contact
Yes
address3
Text (200)
No
Address line 3 for the contact
Yes
address4
Text (200)
No
Address line 4 for the contact
Yes
postCode
Text (50)
Yes
Postcode for the contact
Yes
notes
Text (2000)
No
The contact notes field in Oneserve
Yes
considerations
Text (4000)
No
The contact considerations field in Oneserve
Yes
Request Representations
Example JSON Payload
{
"locations": [
{
"locationRef": "4026421",
"name": "Flat 4. 341 London Road",
"address1": "Flat 4. 341 London Road",
"address2": "St Leonards On Sea",
"address3": "East Sussex",
"address4": "NULL",
"postCode": "TN37 6PA",
"code": "21",
"parentLocationRef": "4026",
"description": "This is a test description",
"groupId": "118",
"considerations": "Two engineers required for the site",
"typeId": "21",
"usageTypdId": "1",
"ignoreUsageTypeOnUpdate": 0,
"regionId": "1",
"clientRef": "1",
"deleted": false,
"statusId": "2",
"latLongSourceExternal": false,
"contacts": [
{
"clientRef": "1",
"contactRef": "test4026421",
"salutation": "Mr",
"forename": "Roger",
"surname": "Test",
"contact1": "",
"contact1Type": "1",
"contact2": "07123456789",
"contact2Type": "10",
"contact3": "test@test.test",
"contact3Type": "6",
"contact4": "",
"contact4Type": "1",
"preferredContact": "1",
"address1": "Address line 1",
"address2": "Address line 2",
"address3": "Address line 3",
"address4": "Address line 4",
"notes": "These are notes",
"considerations": "These are considerations",
"postCode": "EX49HL",
"isPreferred": true
}
]
}
]
}
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
{
"result" : "success",
"result_msg" : ""
}
Troubleshooting
This error occurs if the Verify your This error indicates that something is blocking your connection to the server Open a ticket with the support team with details of your connection so that your access can be verfied 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 Verify the endpoint matches the value specified in this article This error will occur if an unacceptable method has been used in the call such as Ensure that you are using a This response is given if data is passed to the endpoint in a format other than Pass your requests as a JSON object with the This error occurs if you have tried to pass a call that isn't wrapped as a JSON object. For example: Ensure that all calls are valid JSON objects following a similar layout to the example call above 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 Ensure that all fields are filled out according to the field data types listed above 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 Ensure that all fields are filled out according to the field data types listed above This is caused by a non-integer value being used in the Ensure that all fields are filled out according to the field data types listed above This is caused by a non-integer value being used in the Ensure that all fields are filled out according to the field data types listed above This error is returned when a client with the provided ID cannot be found in the system Ensure that the client exists in Oneserve and that all fields are filled out according to the field data types listed above401 Unauthorized
Response
401 Unauthorized
Reason
OS_REST_AUTH_TOKEN
has not been provided, has expired, or does not exist in the systemResolution
OS_REST_AUTH_TOKEN
with support403 Forbidden
Response
403 Forbidden
Reason
Resolution
404 Not Found
Response
404 Not Found
Reason
Resolution
405 Method Not Allowed
Response
405 Method Not Allowed
Reason
GET
or DELETE
Resolution
POST
call to this endpoint415 Unsupported Media Type
Response
415 Unsupported Media Type
Reason
application/json
Resolution
application/json
headerREST0002
Response
{
"result": "fail",
"result_msg": "REST0002",
"result_error_msg": "A JSONObject text must begin with '{' at character..."
}
Reason
[
{
"locationRef": "myref",
...
}
]
Resolution
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
Resolution
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
Resolution
JSONObject "regionId" is not a number
Response
{
"result": "fail",
"result_msg": "JSONObject[\"regionId\"] is not a number"
}
Reason
regionId
fieldResolution
JSONObject "statusId" is not a number
Response
{
"result": "fail",
"result_msg": "JSONObject[\"statusId\"] is not a number"
}
Reason
statusId
fieldResolution
Unable to locate client ref supplied
Response
{
"result": "fail",
"result_msg": "Unable to locate client ref supplied"
}
Reason
Resolution