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/sites/{clientId}/{siteRef}
GET
Gets a site's details based on the client id and unique reference assigned to it.
The endpoint accepts two parameters passed in the URL:
clientId
: The ID of the client in OneservesiteRef
: The unique reference of the site in Oneserve
Response Format Spec
Sites Array
Field Name
Data Type
Description
clientId
Integer
The ID of the client in Oneserve
siteRef
Text (50)
The site reference in Oneserve
siteId
Integer
The site ID in Oneserve
siteType
Text (200)
The name of the site type
siteGroup
Text (100)
The description of the site group
usageType
Text (50)
The usage/tenancy type of the site
region
Text (50)
The site region
name
Text (255)
The site name in Oneserve
description
Text (2000)
The notes field of the site in Oneserve
code
Text (20)
The code of the site
parentLocationRef
Text (50)
The site reference of the parent site
address1
Text (255)
The first line of the site address
address2
Text (255)
The second line of the site address
address3
Text (255)
The third line of the site address
address4
Text (255)
The fourth line of the site address
postcode
Text (20)
The postcode of the site
latitude
BigDecimal
The latitude of the site
longitude
BigDecimal
The longitude of the site
status
Text (50)
The status of the site in Oneserve
area
Text (50)
The area of the site in Oneserve
considerations
Text (1000)
The site considerations field in Oneserve
contacts
Array
An array of information about contacts related to the site
attributes
Array
An array of information relating to the site's attributes
assets
Array
An array of information relating to the site's assets
jobs
Array
An array of information relating to jobs raised against the site
siteLocations
Array
An array of information relating to the site's locations
sitePois
Array
An array of information relating to points of interest on the site
Contacts Array
Field Name
Data Type
Description
ref
Text (50)
The contact reference
salutation
Text (50)
The contact salutation
forename
Text (80)
The forename of the contact
surname
Text (80)
The surname of the contact
contact1
Text (80)
The contact 1 value for the contact
contact1type
Text (50)
The contact 1 type for the contact
contact2
Text (80)
The contact 2 value for the contact
contact2type
Text (50)
The contact 2 type for the contact
contact3
Text (80)
The contact 3 value for the contact
contact3type
Text (50)
The contact 3 type for the contact
contact4
Text (80)
The contact 4 value for the contact
contact4type
Text (50)
The contact 4 type for the contact
preferredContact
Integer (1-4)
The preferred contact (contact1-contact4) for the contact
notes
Text (2000)
The contact notes field in Oneserve
considerations
Text (4000)
The contact considerations field in Oneserve
preferred
Boolean
0 - Contact is not preferred contact for the site
1 - Contact is the preferred contact for the site
startDate
DateTime
The start date/time of the contact
endDate
DateTime
The end date/time of the contact
Attributes Array
Field Name
Data Type
Description
name
Text (200)
The name of the attribute on the site
value
Text (1000)
The value against the attribute on the site
id
Integer
The Oneserve ID for the site attribute
Assets Array
Field Name
Data Type
Description
id
Integer
The ID of the asset in Oneserve
ref
Text (100)
The reference of the asset
siteLocation
Text (200)
The name of the site location in which the asset is located
model
Text (200)
The model of the asset in the asset library in Oneserve
description
Text (1000)
The description of the asset in the asset library in Oneserve
type
Text (200)
The name of the asset type in Oneserve
manufacturer
Text (200)
The name of the asset manufacturer in Oneserve
condition
Text (200)
The name of the asset condition in Oneserve
siteLocationId
Integer
The ID of the site location in Oneserve
attributes
Array
Array of asset attribute data
group
Text (200)
The name of the attribute group
name
Text (200)
The name of the attribute
value
Text (1000)
The value of the attribute
id
Integer
The ID of the asset attribute in Oneserve
Jobs Array
Field Name
Data Type
Description
id
Integer
The job ID in Oneserve
jobRef
Text (50)
The job reference in Oneserve
jobClientRef
Text (50)
The job client reference in Oneserve
jobStatus
Text (80)
The job status in Oneserve
jobDescription
Text (MAX)
The job description in Oneserve
workLogType
Text (50)
The work log type reference in Oneserve
priority
Text (50)
The priority description in Oneserve
supplier
Text (80)
The team name in Oneserve
plannedStartDateTime
DateTime
The job planned start date/time in Oneserve
plannedEndDateTime
DateTime
The job planned end date/time in Oneserve
actualStartDateTime
DateTime
The job actual start date/time in Oneserve
actualEndDateTime
DateTime
The job actual end date/time in Oneserve
createdDateTime
DateTime
The date/time at which the job was created in Oneserve
reportedDateTime
DateTime
The job reported date/time in Oneserve
Site Location Array
Field Name
Data Type
Description
id
Integer
The location ID in Oneserve
name
Text (200)
The name of the location in Oneserve
parentSiteLocationId
Integer
The ID of the parent site location
Site POIs (Points of Interest) Array
Field Name
Data Type
Description
id
Integer
The ID of the point of interest in Oneserve
name
Text (100)
The name of the point of interest in Oneserve
latitude
BigDecimal
The latitude of the point of interest
longitude
BigDecimal
The longitude of the point of interest
disabled
true/false
Whether or not the point of interest is disabled in Oneserve
Available Response Representations
HTTP Code | Description | Schema |
---|---|---|
200 | Site information | Site Information |
400 | Bad Request | Error |
401 | Unauthorized | Error |
403 | Forbidden | Error |
404 | Address Not Found | Error |
405 | Method Not Allowed | Error |
500 | Internal Server Error | Error |
Example JSON Success Response
{
"sites": [
{
"clientId": "1",
"siteRef": "4026",
"siteId": "32474",
"siteType": "Flat",
"siteGroup": "Housing - Default",
"usageType": "Housing",
"region": "Ability Housing - Default",
"name": "Flat 3. 341 London Road",
"description": "This is a test description",
"code": "21",
"parentLocationRef": "4025",
"address1": "Flat 3. 341 London Road",
"address2": "St Leonards On Sea",
"address3": "East Sussex",
"address4": "NULL",
"postcode": "TN37 6PA",
"latitude": "50.85189020",
"longitude": "0.56070250",
"status": "live",
"area": "",
"considerations": "Two engineers required for the site",
"contacts": [
{
"ref": "12266",
"salutation": "Mr",
"forename": "Robin",
"surname": "Test",
"contact1": "0123456789",
"contact1type": "Home Phone",
"contact2": "robin@test.site",
"contact2type": "Email",
"contact3": "",
"contact3type": "Home Phone",
"contact4": "",
"contact4type": "Home Phone",
"preferredContact": "1",
"notes": "These are contact notes",
"considerations": "These are contact considerations",
"preferred": "0",
"startDate": "",
"endDate": ""
}
],
"attributes": [
{
"name": "Question 1",
"value": "",
"id": "262424"
},
{
"name": "Another Date Attribute",
"value": "",
"id": "262420"
},
{
"name": "Question 2",
"value": "",
"id": "262417"
},
{
"name": "Will the outstanding work be chargeable",
"value": "",
"id": "262415"
},
{
"name": "Please rate the work carried out (5 highest, 1 lowest)",
"value": "",
"id": "262436"
},
{
"name": "Please detail outstanding work",
"value": "",
"id": "262443"
},
{
"name": "Question 3",
"value": "",
"id": "262413"
},
{
"name": "Any additional work required",
"value": "",
"id": "262451"
},
{
"name": "Was the tenant satisfied by operatives work?",
"value": "",
"id": "262433"
},
{
"name": "Second Date Attribute Test",
"value": "",
"id": "262455"
},
{
"name": "Question 1",
"value": "",
"id": "262441"
}
],
"assets": [
{
"id": "1026",
"ref": "RF-4026",
"siteLocation": "Laundry Room",
"model": "RF-001",
"description": "Auto generated",
"type": "Washing machine",
"manufacturer": "Tincknell",
"condition": "Good",
"siteLocationId": "933",
"attributes": [
{
"group": "Client Satisfaction Survey",
"name": "And why was there a delay?",
"value": "",
"id": "164"
}
]
}
],
"jobs": [
{
"id": "63136",
"jobRef": "J023T1",
"jobClientRef": "J023T1",
"jobStatus": "Waiting to Start",
"jobDescription": "Fix Washing Machine",
"workLogType": "1. Call Out",
"priority": "1 day",
"supplier": "1 Electrical",
"plannedStartDateTime": "",
"plannedEndDateTime": "",
"actualStartDateTime": "",
"actualEndDateTime": "",
"createdDateTime": "2020-07-12 19:03:49.353",
"reportedDateTime": "2020-07-12 19:03:49.33"
}
],
"siteLocations": [
{
"id": "933",
"name": "Laundry Room",
"parentSiteLocationId": ""
}
],
"sitePois": [
{
"id": "81",
"name": "Garage Forecourt",
"latitude": "50.85183093",
"longitude": "0.56080577",
"disabled": "false"
}
]
}
]
}
Example XML Success Response
<SiteFindResponse>
<sites>
<site>
<clientId>1</clientId>
<siteRef>4026</siteRef>
<siteId>32474</siteId>
<siteType>Flat</siteType>
<siteGroup>Housing - Default</siteGroup>
<usageType>Housing</usageType>
<region>Ability Housing - Default</region>
<name>Flat 3. 341 London Road</name>
<description>This is a test description</description>
<code>21</code>
<parentLocationRef>4025</parentLocationRef>
<address1>Flat 3. 341 London Road</address1>
<address2>St Leonards On Sea</address2>
<address3>East Sussex</address3>
<address4>NULL</address4>
<postcode>TN37 6PA</postcode>
<latitude>50.85189020</latitude>
<longitude>0.56070250</longitude>
<status>live</status>
<area></area>
<considerations>Two engineers required for the site</considerations>
<contacts>
<contact>
<ref>12266</ref>
<salutation>Mr</salutation>
<forename>Robin</forename>
<surname>Test</surname>
<contact1>0123456789</contact1>
<contact1type>Home Phone</contact1type>
<contact2>robin@test.site</contact2>
<contact2type>Email</contact2type>
<contact3></contact3>
<contact3type>Home Phone</contact3type>
<contact4></contact4>
<contact4type>Home Phone</contact4type>
<preferredContact>1</preferredContact>
<notes>These are contact notes</notes>
<considerations>These are contact considerations</considerations>
<preferred>0</preferred>
<startDate></startDate>
<endDate></endDate>
</contact>
</contacts>
<attributes>
<attribute>
<name>Please rate the work carried out (5 highest, 1 lowest)</name>
<value></value>
<id>262436</id>
</attribute>
<attribute>
<name>Question 2</name>
<value></value>
<id>262417</id>
</attribute>
<attribute>
<name>Please detail outstanding work</name>
<value></value>
<id>262443</id>
</attribute>
<attribute>
<name>Another Date Attribute</name>
<value></value>
<id>262420</id>
</attribute>
<attribute>
<name>Second Date Attribute Test</name>
<value></value>
<id>262455</id>
</attribute>
<attribute>
<name>Question 3</name>
<value></value>
<id>262413</id>
</attribute>
<attribute>
<name>Will the outstanding work be chargeable</name>
<value></value>
<id>262415</id>
</attribute>
<attribute>
<name>Question 1</name>
<value></value>
<id>262441</id>
</attribute>
<attribute>
<name>Was the tenant satisfied by operatives work?</name>
<value></value>
<id>262433</id>
</attribute>
<attribute>
<name>Any additional work required</name>
<value></value>
<id>262451</id>
</attribute>
<attribute>
<name>Question 1</name>
<value></value>
<id>262424</id>
</attribute>
</attributes>
<assets>
<asset>
<id>1026</id>
<ref>RF-4026</ref>
<siteLocation>Laundry Room</siteLocation>
<model>RF-001</model>
<description>Auto generated</description>
<type>Washing machine</type>
<manufacturer>Tincknell</manufacturer>
<condition>Good</condition>
<siteLocationId>933</siteLocationId>
<attributes>
<attributes>
<group>Client Satisfaction Survey</group>
<name>And why was there a delay?</name>
<value></value>
<id>164</id>
</attributes>
</attributes>
</asset>
</assets>
<jobs>
<job>
<id>63136</id>
<jobRef>J023T1</jobRef>
<jobClientRef>J023T1</jobClientRef>
<jobStatus>Waiting to Start</jobStatus>
<jobDescription>Fix Washing Machine</jobDescription>
<workLogType>1. Call Out</workLogType>
<priority>1 day</priority>
<supplier>1 Electrical</supplier>
<plannedStartDateTime></plannedStartDateTime>
<plannedEndDateTime></plannedEndDateTime>
<actualStartDateTime></actualStartDateTime>
<actualEndDateTime></actualEndDateTime>
<createdDateTime>2020-07-12 19:03:49.353</createdDateTime>
<reportedDateTime>2020-07-12 19:03:49.33</reportedDateTime>
</job>
</jobs>
<siteLocations>
<siteLocation>
<id>933</id>
<name>Laundry Room</name>
<parentSiteLocationId></parentSiteLocationId>
</siteLocation>
</siteLocations>
<sitePois>
<sitePoi>
<id>81</id>
<name>Garage Forecourt</name>
<latitude>50.85183093</latitude>
<longitude>0.56080577</longitude>
<disabled>false</disabled>
</sitePoi>
</sitePois>
</site>
</sites>
</SiteFindResponse>
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 could occur if the endpoint is not entered correctly or a non-existent client ID is passed in the request Verify the endpoint matches the value specified in this article. Check that the client ID exists in your Oneserve system. This error will occur if an unacceptable method has been used in the call such as Ensure that you are using a This error is returned when no sites matching the client ID and site reference are found in the system Ensure that you are passing the correct details for the site in question in the call401 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
POST
or DELETE
Resolution
GET
call to this endpointREST0001
Response
JSON Response
{
"result": "fail",
"result_msg": "REST0001",
"result_error_msg": "Site with client id: '1' and site ref: 'siteref' not found"
}
XML response
<root>
<result>fail</result>
<result_msg>REST0001</result_msg>
<result_error_msg>Site with client id: '1' and site ref: 'siteref' not found</result_error_msg>
</root>
Reason
Resolution