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