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
clientIdInteger
The ID of the client in Oneserve
siteRefText (50)
The site reference in Oneserve
siteIdInteger
The site ID in Oneserve
siteTypeText (200)
The name of the site type
siteGroupText (100)
The description of the site group
usageTypeText (50)
The usage/tenancy type of the site
regionText (50)
The site region
nameText (255)
The site name in Oneserve
descriptionText (2000)
The notes field of the site in Oneserve
codeText (20)
The code of the site
parentLocationRefText (50)
The site reference of the parent site
address1Text (255)
The first line of the site address
address2Text (255)
The second line of the site address
address3Text (255)
The third line of the site address
address4Text (255)
The fourth line of the site address
postcodeText (20)
The postcode of the site
latitudeBigDecimal
The latitude of the site
longitudeBigDecimal
The longitude of the site
statusText (50)
The status of the site in Oneserve
areaText (50)
The area of the site in Oneserve
considerationsText (1000)
The site considerations field in Oneserve
contactsArray
An array of information about contacts related to the site
attributesArray
An array of information relating to the site's attributes
assetsArray
An array of information relating to the site's assets
jobsArray
An array of information relating to jobs raised against the site
siteLocationsArray
An array of information relating to the site's locations
sitePoisArray
An array of information relating to points of interest on the site
Contacts Array
Field Name
Data Type
Description
refText (50)
The contact reference
salutationText (50)
The contact salutation
forenameText (80)
The forename of the contact
surnameText (80)
The surname of the contact
contact1Text (80)
The contact 1 value for the contact
contact1typeText (50)
The contact 1 type for the contact
contact2Text (80)
The contact 2 value for the contact
contact2typeText (50)
The contact 2 type for the contact
contact3Text (80)
The contact 3 value for the contact
contact3typeText (50)
The contact 3 type for the contact
contact4Text (80)
The contact 4 value for the contact
contact4typeText (50)
The contact 4 type for the contact
preferredContactInteger (1-4)
The preferred contact (contact1-contact4) for the contact
notesText (2000)
The contact notes field in Oneserve
considerationsText (4000)
The contact considerations field in Oneserve
preferredBoolean
0 - Contact is not preferred contact for the site
1 - Contact is the preferred contact for the site
startDateDateTime
The start date/time of the contact
endDateDateTime
The end date/time of the contact
Attributes Array
Field Name
Data Type
Description
nameText (200)
The name of the attribute on the site
valueText (1000)
The value against the attribute on the site
idInteger
The Oneserve ID for the site attribute
Assets Array
Field Name
Data Type
Description
idInteger
The ID of the asset in Oneserve
refText (100)
The reference of the asset
siteLocationText (200)
The name of the site location in which the asset is located
modelText (200)
The model of the asset in the asset library in Oneserve
descriptionText (1000)
The description of the asset in the asset library in Oneserve
typeText (200)
The name of the asset type in Oneserve
manufacturerText (200)
The name of the asset manufacturer in Oneserve
conditionText (200)
The name of the asset condition in Oneserve
siteLocationIdInteger
The ID of the site location in Oneserve
attributesArray
Array of asset attribute data
groupText (200)
The name of the attribute group
nameText (200)
The name of the attribute
valueText (1000)
The value of the attribute
idInteger
The ID of the asset attribute in Oneserve
Jobs Array
Field Name
Data Type
Description
idInteger
The job ID in Oneserve
jobRefText (50)
The job reference in Oneserve
jobClientRefText (50)
The job client reference in Oneserve
jobStatusText (80)
The job status in Oneserve
jobDescriptionText (MAX)
The job description in Oneserve
workLogTypeText (50)
The work log type reference in Oneserve
priorityText (50)
The priority description in Oneserve
supplierText (80)
The team name in Oneserve
plannedStartDateTimeDateTime
The job planned start date/time in Oneserve
plannedEndDateTimeDateTime
The job planned end date/time in Oneserve
actualStartDateTimeDateTime
The job actual start date/time in Oneserve
actualEndDateTimeDateTime
The job actual end date/time in Oneserve
createdDateTimeDateTime
The date/time at which the job was created in Oneserve
reportedDateTimeDateTime
The job reported date/time in Oneserve
Site Location Array
Field Name
Data Type
Description
idInteger
The location ID in Oneserve
nameText (200)
The name of the location in Oneserve
parentSiteLocationIdInteger
The ID of the parent site location
Site POIs (Points of Interest) Array
Field Name
Data Type
Description
idInteger
The ID of the point of interest in Oneserve
nameText (100)
The name of the point of interest in Oneserve
latitudeBigDecimal
The latitude of the point of interest
longitudeBigDecimal
The longitude of the point of interest
disabledtrue/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 DELETEResolution
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