sites 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/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 Oneserve
  • siteRef: 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

 

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 could occur if the endpoint is not entered correctly or a non-existent client ID is passed in the request

Resolution

Verify the endpoint matches the value specified in this article. Check that the client ID exists in your Oneserve system.

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 POST or DELETE

Resolution

Ensure that you are using a GET call to this endpoint

REST0001

Response

JSON Response
{
    "result": "fail",
    "result_msg": "REST0001",
    "result_error_msg": "Site with client id: &#39;1&#39; and site ref: &#39;siteref&#39; not found"
}
XML response
<root>
    <result>fail</result>
    <result_msg>REST0001</result_msg>
    <result_error_msg>Site with client id: &#39;1&#39; and site ref: &#39;siteref&#39; not found</result_error_msg>
</root>

Reason

This error is returned when no sites matching the client ID and site reference are found in the system

Resolution

Ensure that you are passing the correct details for the site in question in the call