addApointment API

Avatar
Ciarán Ainsworth
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/rs/addAppointment

POST

Adds an appointment to a job. Requires that provided activities are not currently assigned to an appointment.

File Format Spec

 

Available fields
Field Name Data Type Mandatory? Description
jobRef Char(20) Yes The Oneserve job reference
activities Array Yes An array of unassigned or incomplete activity ids
id Integer Yes The ID of the activity
startDate Date Yes The date that the appointment is scheduled to start
startTime Time Yes The time at which the appointment is scheduled to start
duration Integer No The duration of the appointment (defaults to activity duration)
resourceId Integer No The ID of the resource assigned to the cost. If not provided a pooled appointment will be booked
clientRef Char(80) No The client reference of the
notes Char(1000) No Notes to be added to the appointment
overridePriorities Boolean No 1 = True (default)
0 = False
zoneCriteria Char(20) No Determines the postcode coverage to use
* Primary (default)
* Both
* Any
allowSecondary Boolean No Whether or not to allow secondary services
1 = True
0 = False
sendNotification Boolean No Whether or not to send a notification. Defaults to False

 

Request Representations

 

JSON payload example 
{
    "jobRef" : "J023TG",
    "activities" : [
        {"id":"137196"}, 
        {"id":"137197"}
    ],
    "startDate" : "19/07/2020",
    "startTime" : "9:23",
    "duration" : "60",
    "clientRef" : "14245",
    "resourceId": "1100",
    "notes": "This is an API appointment",
    "overridePriorities":"1",
    "zoneCriteria" : "ANY",
    "allowSecondary" : "1",
    "sendNotification":"0"
}

 

Available Response Representations

HTTP Code Description Schema
200 Appointment(s) Posted appointmentId Integer
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 Success Response

{
    "result": "success",
    "result_msg": "",
    "appointmentId": "42935"
}

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 should only occur if the endpoint has been mistyped in some way, which will lead the call to an endpoint that does not exist

Resolution

Verify the endpoint matches the value specified in this article

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

Resolution

Ensure that you are using a POST call to this endpoint

One or more activities are either already assigned or complete or are not linked to specified job

Response

{
    "result": "fail",
    "result_msg": "REST0001",
    "result_error_msg": "One or more activities are either already assigned or complete or are not linked to specified job"
}

Reason

This error occurs if the provided activity IDs are already assigned to a resource, are fully complete, or don't belong to the job reference passed

Resolution

Ensure that the job reference and activity IDs match and that the activities are not currently