September 27, 2020 19:50
Updated

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

Appointment Details

/rest/appointments/{id}

Activity Details

/rest/appointments/{id}/activities/

GET

Returns details for a single appointment or an array of appointments depending on the format of the URL. Up to 20 activity IDs can be passed in a single call.

Activities relating to a single appointment can also be returned by calling the activities endpoint for the appointment ID.

Single Appointment

Example URL

/rest/appointments/137121

Multiple Appointments

Example URL

/rest/appointments?ids=137121,137120

Appointment Activities

/rest/appointments/137121/activities

Response Format Spec

`/rest/appointments/`

Response Fields

Field Name	Data Type	Description
`actualEndDate`	DateTime	Actual end time.
`actualStartDate`	DateTime	Actual start time.
`allowSecondaryService`	boolean	Secondary Service allowed state.
`allowZoneType`	integer	Zone type allowed.
`allowedOtherPriorities`	boolean	Allow other Priorities state.
`basicDuration`	integer	Basic calculated duration for this Appointment.
`conflict`	boolean	Appointment in conflict state.
`createdDate`	DateTime	Date this Appointment was created.
`dayDivisionId`	integer	ID for the DayDivision associated to this Appointment.
`driveTime`	integer	Drive time associated with this Appointment.
`duration`	integer	Duration of this Appointment (in minutes)
`durationFixed`	boolean	Duration fixed state.
`fixedByResource`	boolean	Appointment fixed by Resource state.
`id`	integer	Unique ID for the Appointment.
`lastModified`	DateTime	Date this Appointment was last modified.
`lateAppointmentReason`	string	Reason for late Appointment.
`notes`	string	Notes for this Appointment.
`oldStatus`	integer	ID of this Appointment's old status.
`plannedEndDate`	DateTime	Planned end time.
`plannedStartDate`	DateTime	Planned start time.
`ref`	string	Client reference for this Appointment.
`rescheduledReason`	string	Reason for reschedule.
`resolution`	string	Notes on resolution.
`resourceId`	integer	ID of the Resource doing this Appointment.
`sendLetter`	boolean	Notifications to be sent state.
`sequence`	integer	Sequence value of this Appointment.
`serviceId`	integer	ID for the Service associated to this Appointment.
`statusId`	integer	ID of this Appointment's status.
`userId`	integer	ID of the Appointment booking User.
`workStateChangeDate`	DateTime	Date the work state chagned for this Appointment.
`workTimeTypeId`	integer	ID for the WorkTimeType associated to this Appointment.

`/rest/appointments/{id}/activities`

Response Fields

Field Name	Data Type	Description
`assetId`	Integer	The ID of the asset against which the activity is loaded
`completedQuantity`	Decimal	The completed quantity of the activity
`duration`	Integer	The duration of the activity
`description`	Text (1000)	The description of the activity
`id`	Integer	The ID of the activity
`isDeleted`	True/False	Whether the activity is deleted or not
`jobId`	Integer	The ID of the job in Oneserve
`lastModified`	DateTime	The date/time at which the activity was last modified
`libraryActivityId`	Integer	The ID of the associated library activity
`quantity`	Decimal	The quantity of the activity on the job
`serviceId`	Integer	The ID of the service
`siteLocationId`	Integer	The ID of the site location against which the activity is loaded
`status`	Integer (1-4)	1 - PENDING 2 - APPROVED 3 - REJECTED 4 - DELETED
`supplierId`	Integer	The ID of the team assigned to the activity
`resourceId`	Integer	The ID of the resource assigned to the activity
`ref`	Text (200)	The reference of the activity
`activityCategoryId`	Integer	The ID of the activity category

Available Response Representations

HTTP Code	Description	Schema
200	Document Information	Document 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

`/rest/appointments/`

Example Success Response

{
    "appointments": [
        {
            "allowSecondaryService": false,
            "allowZoneType": 1,
            "alloweOtherPriorities": false,
            "basicDuration": 300,
            "conflict": false,
            "createdDate": "2020-09-24T10:34:31.673Z",
            "dayDivisionId": 1,
            "driveTime": 0,
            "duration": 300,
            "durationFixed": false,
            "fixedByResource": false,
            "id": 3113905,
            "lastModified": "2020-09-24T10:34:21.580Z",
            "lateAppointmentNotes": "",
            "notes": "",
            "oldStatus": 0,
            "plannedEndDate": "2020-09-25T12:13:00Z",
            "plannedStartDate": "2020-09-25T07:13:00Z",
            "ref": 3113905,
            "resourceId": 851,
            "sendLetter": false,
            "sequence": 1,
            "serviceId": 81,
            "statusId": 2,
            "userId": 2030
        },
        {
            "allowSecondaryService": false,
            "allowZoneType": 1,
            "alloweOtherPriorities": false,
            "basicDuration": 370,
            "conflict": false,
            "createdDate": "2020-09-24T10:38:27.113Z",
            "dayDivisionId": 1,
            "driveTime": 0,
            "duration": 370,
            "durationFixed": true,
            "fixedByResource": false,
            "id": 3113906,
            "lastModified": "2020-09-24T10:38:18.247Z",
            "lateAppointmentNotes": "",
            "notes": "",
            "oldStatus": 0,
            "plannedEndDate": "2020-09-28T13:17:00Z",
            "plannedStartDate": "2020-09-28T07:07:00Z",
            "ref": 3113906,
            "resourceId": 1069,
            "sendLetter": false,
            "sequence": 1,
            "serviceId": 81,
            "statusId": 2,
            "userId": 2030
        }
    ]
}

`/rest/appointments/{id}/activities/`

Example Success Response

{
    "activities": [
        {
            "completedQuantity": "0.00000",
            "description": "BATH:RENEW 1700MM ACRYLIC",
            "duration": 300,
            "id": 6709110,
            "isDeleted": false,
            "jobId": 2312622,
            "lastModified": "2020-09-24T10:38:15.400Z",
            "libraryActivityId": 38152,
            "quantity": "1.00000",
            "resourceId": 1069,
            "serviceId": 81,
            "status": 2,
            "supplierId": 48
        }
    ]
}

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 verified

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 these endpoints