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