appointments API

Avatar
Oneserve Product Team
  • Updated
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

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