YellowSchedule API

API Reference

YellowSchedule API for Developers

Introduction

YellowSchedule is a secure platform for scheduling appointments with clients, and storing and tracking client (patient) details. This API allows developers to write functions to allow other systems to integrate directly with YellowSchedule. This can allows other system to, for example, create or view contacts or appointments directly in YellowSchedule.

Things you should know:

  • This API is organised around RESTful web services and all API requests return JSON responses.
  • Keep your API Key(s) safe. You should never expose your secret API Key in public client side source code or publicly accessible areas such GitHub.
  • If you just want to take appointment bookings on your website, you do not need this API. We have easy to add booking widget which plug into any website. The API is not required for using our booking widget - you simply include a snippet of code onto your website source code to use the booking widget. The snippet is available by going to "Settings" (top right menu) >> "Install code" and can simply be pasted in your website source. Additionally we also have Wordpress, Joomla, and Drupal Plugins for the booking widget). More on setting up live bookings on your website WITHOUT requiring the use of this API.

Authentication

Authenticate your account when using the API by including your secret API key in the header of the request. Manage your API keys within the YellowSchedule App. Keys can be refreshed to ensure access is controlled and keys can be revoked if API access is no longer required.

All API requests must have a valid API key as part of the header of the request. The following example shows a CURL call to request all services on the account.

$ curl -H "Authorization: bearer *-API Key-*" https://www.yellowschedule.com/app/api/v2/services -X GET
$url = "https://www.yellowschedule.com/app/api/v2/services"; $APItoken =*-API Key-*; // << insert YOUR api key and build header $headers = array('Authorization: bearer '.$APItoken, 'Content-Type: application/json'); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // <-- pass in the header with API Key curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); // <-- GET Request, can also be POST,PUT or DELETE methods $result = curl_exec($ch); curl_close($ch); echo $result; // <-- see the result
require 'net/http' require 'uri' uri = URI.parse("https://www.yellowschedule.com/app/api/v2/services") request = Net::HTTP::Get.new(uri) request["Authorization"] = "bearer *-API Key-*" response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http| http.request(request) end # response.code # response.body
import requests headers = { 'Authorization': 'bearer *-API Key-*', } requests.get('https://www.yellowschedule.com/app/api/v2/services', headers=headers)

API Keys

When creating an API key it's a good idea to create your key with the minimal functionality that you require. For example if you only need the API for the ability to create appointments within YellowSchedule then you should create a key that only grants access to create appointments prevents access to all other functions. This is useful from a security perspective as tailoring the API key to suit your needs can help reduce the risk of exposure if there was a compromise of your system or API key. You can create as many keys as you like within YellowSchedule, with each key valid for only a single API function. You can still create just one key with access to all API functions. More on HTTP Methods/CRUD operations in YellowSchedule

Select API functionality required

Live Example

The following example includes a live API key (from a test account) to return the contacts. Note that the included API key in the request provided here only allows access for View ("GET") requests on Contacts (https://www.yellowschedule.com/app/api/v2/contacts) and trying to use this same API key for any other request will not work. As mentioned in the previous paragraph on API keys. You can use this same idea to control access to only what is required.

$ curl -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjp7ImNvbiI6InIifSwibSI6IjE2NDcxIiwidCI6MTQ4MDU5NzE5NCwiaWQiOjV9.9aExba9qw5rYr0b01dy01VezBJGb1pF-IsR9jSldO5Q" https://www.yellowschedule.com/app/api/v2/contacts -X GET
$url = "https://www.yellowschedule.com/app/api/v2/contacts"; $APItoken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjp7ImNvbiI6InIifSwibSI6IjE2NDcxIiwidCI6MTQ4MDU5NzE5NCwiaWQiOjV9.9aExba9qw5rYr0b01dy01VezBJGb1pF-IsR9jSldO5Q"; $headers = array('Authorization: bearer '.$APItoken, 'Content-Type: application/json'); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // <-- pass in the header with API Key curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); $result = curl_exec($ch); curl_close($ch); echo $result; // <-- see the result
require 'net/http' require 'uri' uri = URI.parse("https://www.yellowschedule.com/app/api/v2/contacts") request = Net::HTTP::Get.new(uri) request["Authorization"] = "bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjp7ImNvbiI6InIifSwibSI6IjE2NDcxIiwidCI6MTQ4MDU5NzE5NCwiaWQiOjV9.9aExba9qw5rYr0b01dy01VezBJGb1pF-IsR9jSldO5Q" response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http| http.request(request) end # response.code # response.body
import requests headers = { 'Authorization': 'bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjp7ImNvbiI6InIifSwibSI6IjE2NDcxIiwidCI6MTQ4MDU5NzE5NCwiaWQiOjV9.9aExba9qw5rYr0b01dy01VezBJGb1pF-IsR9jSldO5Q', } requests.get('https://www.yellowschedule.com/app/api/v2/contacts', headers=headers)

It should return JSON data containing a listing of the contacts on that test account.

JSON Response
{ "contacts": [{ "contact_id": *id*, "created_utc": "2016-01-15 12:45:56", "edited_utc": "2016-01-15 13:00:00", "firstname": "john", "lastname": "doe", "email": "test1@test.com", "cellphone": "123456789", "dob": "2000-12-25", "notes": "Some simple notes for the contact.. all contact data is encrypted in transfer and at rest!" }] }

(You may notice the JSON returned in this example also includes "user_defined_data_fields" and "paginginfo" sections, more on this later)

Errors

HTTP response codes indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g. incorrect authentication, or validation error). Codes in the 5xx range indicate an error on our end. (If you discover an error in the 5xx range, we would appreciate a quick note regarding how you came across the problem).

HTTP response code Description
200 OK (No error - everything worked as expected)
400 Bad Request (The request was unacceptable)
401 Unauthorized (No API key, or revoked or invalid API key provided for the request)
405 Method Not Allowed
409 Duplicate record
422 Validation error (Invalid parameters)
429 dailyLimitExceeded (Indicates you have exceeded the daily API quota limit.
Please contact us if you need this limit raised)
500 Application or server error (something went wrong on our end)
All errors contain a description of the error, eg: HTTP 401 {"error":"invalid token or token was revoked or changed"}

HTTP Methods

Allowed HTTP methods are POST, GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations. You should use the correct method for the operation you require, for example, if you want to use the API to return a list of contacts use the "GET" method instead of "POST", "PUT" or "DELETE".

When creating your API key you can see which methods are available for each function. You can also specifiy the permitted methods for API keys allowing you to for example create a key with "GET" and "POST" operations on contacts, but perhaps no "DELETE" or "PUT" methods.

The following API functions are currently available. Functionality will be regularly added to (however if there's some API functionality that you would like to request please contact us).

Function URL Methods
Appointments https://www.yellowschedule.com/app/api/v2/appointments GET - for viewing either an indiviual appointment or a list of appointments in between a specified start and end date range
POST - for creating an appointment
PUT - for updating an appointment
DELETE - for deleting an appointment
Available Slots https://www.yellowschedule.com/app/api/v2/availableSlots GET - for showing free unscheduled timeslots available for users
Contacts https://www.yellowschedule.com/app/api/v2/contacts GET - show a specific contact or a listing of contacts
POST - create new contacts on the system
PUT - for updating a contact
DELETE - for deleting a contact
Services https://www.yellowschedule.com/app/api/v2/services GET - show a listing of appointment services
Users https://www.yellowschedule.com/app/api/v2/users GET - show listing of the users

Passing Parameters to the API

There are currently two ways to pass parameters into the API. Through a query string in the URL (for GET and DELETE methods) or Posted through the body as a JSON object (POST and PUT methods). See examples below for passing params in both GET and POST requests:

1. A fetch (GET) is requested on all appointments between a start (range_start) and end point (range_end). (2016-11-29 09:30:00 - 2016-12-02 17:45:00) and for a particular user (user with id:usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY) on the account. Parameters are passed in for "range_start", "range_end" and "user_id".

2. A (POST) is submitted to create an appointment on (2016-11-29 09:30:00 - 2016-11-29 10:00:00) for a particular user (user with id:usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY) with a title (title:initial consultation 30 minutes) on the account. Parameters are passed in for "start", "end", "title" and "user_id".

These parameters will be validated on our end before the request can be satisfied. If a parameter, such as a date, is entered incorrectly, it will result in a 422 validation error code. The details of the error should explain the date format required. More on error codes.

Params passed through url (GET and DELETE Methods)

$ curl -G -H "Authorization: bearer *-API Key-*" --data-urlencode "range_start=2016-11-29 09:30:00" --data-urlencode "range_end=2016-12-02 17:45:00" --data-urlencode "user_id=usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY" https://www.yellowschedule.com/app/api/v2/appointments -X GET
$url = "https://www.yellowschedule.com/app/api/v2/appointments"; $APItoken = "*-API Key-*"; $headers = array('Authorization: bearer '.$APItoken, 'Content-Type: application/json'); $fields = array( "range_start"=>"2016-11-29 09:30:00", "range_end"=>"2016-12-02 17:45:00", "user_id"=>"usr_90TQMB3TBB1U3gFM4hERzN1L2JEe0tCb" ); $url .= "?".http_build_query($fields); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); $result = curl_exec($ch); curl_close($ch); echo $result; // <-- see the result
require 'net/http' require 'uri' uri = URI.parse("https://www.yellowschedule.com/app/api/v2/appointments") fields = { :range_start => '2016-11-29 09:30:00', :range_end => '2016-12-02 17:45:00', :user_id => 'usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY' } uri.query = URI.encode_www_form(fields) request = Net::HTTP::Get.new(uri) request["Authorization"] = "bearer *-API Key-*" response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http| http.request(request) end # response.code # response.body
import requests headers = { 'Authorization': 'bearer *-API Key-*', } fields = ( ('range_start', '2016-11-29 09:30:00'), ('range_end', '2016-12-02 17:45:00'), ('user_id', 'usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY'), ) requests.get('https://www.yellowschedule.com/app/api/v2/appointments', headers=headers, params=fields)


Params posted through Body (POST and PUT Methods)

$ curl -H "Authorization: bearer *-API Key-*" https://www.yellowschedule.com/app/api/v2/appointments -d "{\"start\":\"2016-11-29 09:30:00\",\"end\":\"2016-11-29 10:00:00\",\"title\":\"initial consultation 30 minutes\",\"user_id\":\"usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY\"}" -X POST
$url = "https://www.yellowschedule.com/app/api/v2/appointments"; $APItoken = "*-API Key-*"; $headers = array('Authorization: bearer '.$APItoken, 'Content-Type: application/json'); $fields = array( "start"=>"2016-11-29 09:30:00", "end"=>"2016-11-29 10:00:00", "title"=>"initial consultation 30 minutes", "user_id"=>"usr_90TQMB3TBB1U3gFM4hERzN1L2JEe0tCb" ); $jsonData = json_encode($fields); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData); $result = curl_exec($ch); curl_close($ch); echo $result; // <-- see the result
require 'net/http' require 'uri' require 'json' uri = URI.parse("https://www.yellowschedule.com/app/api/v2/appointments") request = Net::HTTP::Post.new(uri) request["Authorization"] = "bearer *-API Key-*" request.body = JSON.dump({ "start" => "2016-11-29 09:30:00", "end" => "2016-11-29 10:00:00", "title" => "initial consultation 30 minutes", "user_id" => "usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY" }) response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http| http.request(request) end # response.code # response.body
import requests headers = { 'Authorization': 'bearer *-API Key-*', } data = '{"start":"2016-11-29 09:30:00","end":"2016-11-29 10:00:00","title":"initial consultation 30 minutes","user_id":"usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY"}' requests.post('https://www.yellowschedule.com/app/api/v2/appointments', headers=headers, params=data)

Webhooks

Webhooks can be enabled by going to "Settings" (top right menu) >> "Webhooks". You can use Webhooks to be programatically notified about changes on your YellowSchedule account (for example whenever an appointment changes). When enabling webhooks, you must provide an endpoint to receive the notification. You can also select the type of webhook events that you want to be notified about. Whenever an appointment or a contact is created, updated or deleted, your application can receive a HTTP POST describing the type of change. The following webhook types are currently supported:

  • appointment.created
  • appointment.updated
  • appointment.deleted
  • contact.created
  • contact.updated
  • contact.deleted

Responding to a webhook:

Your endpoint should return a 200 HTTP status code to indicate that the webhook was successfully received. Any other status code will indicate a failure in delivery of the webhook. In this case, YellowSchedule will try to resend the webhook. We'll try up to 15 times with an exponential backoff period.

To verify the authenticity of the webhook and for security reasons, the payload will only contain the ID of the contact or appointment that was changed. Sensitive data such as client or appointment data will never be sent in webhooks. Your application will need to be configured to use the API to retrieve the actual changes.

Webhook payload
{ "webhook_id":"ys_apt70a47393ce381a5f42", "webhook_created":1494422644, "type":"appointment.created", "appointment_id_list": [ {"id":"apt_90TQnJjVwVET0RjcVR0YHF3YK9UY1MzN"}, {"id":"apt_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM"} ], "livemode":true }


Payload

Field Type Description
webhook_id string Unique webhook id (created by YellowSchedule)
webhook_created int GMT Unix timestamp in seconds when the event occurred
type string type of the event
appointment_id_list
or customer_id_list
list list of appointments or contacts
id String Unique id of the appointment or contact
livemode boolean true or false whether is a testing or a live webhook

API Reference

Appointments
URL Methods
https://www.yellowschedule.com/app/api/v2/appointments GET - for viewing either an indiviual appointment or a list of appointments in between a specified start and end date range
POST - for creating an appointment
PUT - for updating an appointment
DELETE - for deleting an appointment

Function: Appointments (GET)

Description: You can either specifiy an appointment_id to view a specific appointment, or instead set a date range (range_start, range_end) for a list of appointments to be returned. You can limit returned appointments to a particular user's appointments also using the param "user_id".

Parameters

Field Type Description
appointment_id string Appointment unique id. Returns just the one appointment, all other parameters passed will be ignored. (When a GET is performed on a specific appointment_id it will return a full list of "contacts" connected to the appointment. This will also include a status field, eg cancelled/confirmed)
user_id string If multiuser account, limit return of appointments to this user. Must be valid user_id of a user on the account for the provided API key.
range_start datetime Datetime specifying the START point of the appointments to be returned in the format YYYY-MM-DD HH:MM:SS eg: 2016-10-28 08:15:00 (which equals the 28th of Oct 2016 at 8:15am)
range_end datetime Datetime specifying the END point of the appointments to be returned. range_end must be a datetime after the starttime.
page number Returned appointments may be broken into pages, requiring a page number to be passed in (see Pagination)


"GET on appointments" JSON response sample

{ "appointments": [{ "id": "apt_90TQnJjVwVET0RjcVR0YHF3YK9UY1MzN", "user_id": "usr_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM", "title": "a title, or service name", "service_id": "ser_90TUspnNlV2YKV3MsVkSMl2VxljW4V3a", "created": "16|10|26|18|18", "start": "16|10|27|7|00", "end": "16|10|27|7|30", "loc_id": "0", "note": "notes for the appointment?", "tz": "Europe\/Dublin", "color": "b04efc", "contact_count": "1", "contact_status": "confirmed" },{ "id": ... }], "paginginfo": ... }


Response

Field Type Description
Appointments list list of appointments
id string Unique id of the appointment
user_id string user_id of the user who the appointment belongs to
title string the title of the appointment. If services are used this will show the text of the selected service for the appointment
service_id string service_id of the appointment.
created datetime the datetime string the appointment was logged as being created at
start datetime the datetime string the appointment starts at. Time is in UTC timezone.
end datetime the datetime string the appointment ends at. Time is in UTC timezone.
loc_id string location id for the appoinmtent if locations are used
note string user entered notes for the appointment
tz string timezone of the appointment
color string hexadecimal color of appointment. Null if no color has specifically been assigned
contact_count number number of contacts that this appointment has selected for it
contact_status string status of the contact for the appointment, eg confirmed/cancelled/dna
paginginfo list Details of paging (see paragraph on Pagination)


Function: Appointments (POST)

Description: Create appointments on YellowSchedule using the API. Appointments must be created for a user and have a start and end datetime. Appointments can be created with one or multiple contacts (patients) assigned to the appointment. They can also optionally be created with a service (eg xray), location (eg, SF office), or a room (or multiple rooms or other resources)

Parameters

Field Type Description
user_id string Unique id of the user. Appointments created are assigned to a user and show on their calendar
start datetime Datetime specifying the Beginning time of the appointment to be created. Format YYYY-MM-DD HH:MM:SS eg: 2016-10-28 08:15:00 (which equals the 28th of Oct 2016 at 8:15am)
end datetime Datetime specifying the END of the appointment to be created. Format YYYY-MM-DD HH:MM:SS eg: 2016-10-28 08:45:00 (which equals the 28th of Oct 2016 at 8:45am)
title string Title for the appointment
contact_id string Id for the contact. This is who the appointment is with. You can set the "reminders" param to true (see below) to setup text and/or email reminders to be sent to the contact before the appointment.
contact_ids array of string Similar to above. Use param "contact_ids" if the appointment to be created is with multiple contacts, eg a group appointment. Use param "contact_id" where there's a single contact or "contact_ids" where they may be multiple contacts. Don't use both.

If group appointments are required then you should switch on "Class Bookings" within YellowSchedule. This is done at "Settings" >> "Calendar Settings" >> "Enable class bookings".
service_id string Service id for appointment, eg a service such as "xray" will have a unique id which can be passed in to set the appointment with the correct service.

Also see Services API function to get a list of services on the account.
room_id string If Rooms (or resources) are used, you can use the API to create an appointment for a specific room or other resource.

See more on Room Scheduling.
room_ids array of string As above. However use this if an appointment to be created for multiple rooms or other resources at the same time. Use "room_id" for singular or "room_ids" for multiple. Don't use both.
location_id string If multiple locations exist for an account, you can set a particular location for the appointment. (Reminder emails/texts can be configured to refer the client to this location for their appointment)
reminders boolean If this is set to true then a default set of appointment reminders will be set to go out to the client(s) before this appointment begins. If not specified this is switched off for appointments created using the api.

Be careful testing reminders! If reminders are switched on, and you create a lot of test appointments with clients then a lot of reminders are going to begin going to those clients. You should begin testing with "reminders" left off until you are happy creating appointments through the API.

If you want to use reminder functionality please note that default reminders are set up within YellowSchedule at "Settings" >> "Reminder Settings". Reminders can be configured differently for each of your users on the account. Standard setup is an email reminder 5 days before the appointment begins and a text message reminder 1 day before the appointment but this can be changed and you also have full control over the content of the messages. Sent and recieved messages to contacts can be seen in the contacts' record within YellowSchedule.
bookable boolean Default is off. This option may only be used if "User selectable booking slots" are switched on within YellowSchedule.


"POST on appointments" JSON response sample

{ "status":"success", "created_appointment_id":"apt_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM" }


Response

Field Type Description
status string Success (or failure) message
created_appointment_id string Unique id of the newly created appointment

Function: Appointments (PUT)

Description: update an appointment on YellowSchedule using the API. Appointments can be updated sending only the param that you want to change. If you want to clear a specific field, send an empty string in the parameter.

Parameters

Field Type Description
appointment_id string Unique appointment id (created by YellowSchedule)
user_id string Unique id of the user. Appointments updated can be assigned to a user different user.
start datetime Datetime specifying the Beginning time of the appointment to be updated. Format YYYY-MM-DD HH:MM:SS eg: 2016-10-28 08:15:00 (which equals the 28th of Oct 2016 at 8:15am)
end datetime Datetime specifying the END of the appointment to be updated. Format YYYY-MM-DD HH:MM:SS eg: 2016-10-28 08:45:00 (which equals the 28th of Oct 2016 at 8:45am)
title string Title for the appointment
contact_id string Id for the contact. This is who the appointment is with.
contact_ids array of string Similar to above. Use param "contact_ids" if the appointment to be updated is with multiple contacts, eg a group appointment. Use param "contact_id" where there's a single contact or "contact_ids" where they may be multiple contacts. Don't use both.

If group appointments are required then you should switch on "Class Bookings" within YellowSchedule. This is done at "Settings" >> "Calendar Settings" >> "Enable class bookings".
service_id string Service id for appointment, eg a service such as "xray" will have a unique id which can be passed in to set the appointment with the correct service.

Also see Services API function to get a list of services on the account.
room_id string If Rooms (or resources) are used, you can use the API to update an appointment for a specific room or other resource.

See more on Room Scheduling.
room_ids array of string As above. However use this if an appointment to be updated for multiple rooms or other resources at the same time. Use "room_id" for singular or "room_ids" for multiple. Don't use both.
location_id string If multiple locations exist for an account, you can set a particular location for the appointment.
bookable boolean Default is off. This option may only be used if "User selectable booking slots" are switched on within YellowSchedule.

"PUT on appointment" JSON response sample

{ "status":"success", "updated_appointment_id":"apt_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM" }


Response

Field Type Description
status string Success (or failure) message
updated_appointment_id string Unique id of updated appointment

Function: Appointments (DELETE)

Description: Delete an appointment on YellowSchedule using the API.

Parameters

Field Type Description
appointment_id string Unique appointment id (created by YellowSchedule)

"DELETE on appointment" JSON response sample

{ "status":"success", "deleted_appointment_id":"apt_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM" }


Response

Field Type Description
status string Success (or failure) message
deleted_appointment_id string Unique id of deleted appointment
Available Slots
URL Methods
https://www.yellowschedule.com/app/api/v2/availableSlots GET - for showing free slots for users (available for booking)

Function: Available Slots (GET)

Description: You can use the available slots API function to return the free (bookable) slots for a user. Instead of returning the appointments for a user, this function returns the free 'gaps' between appointments for that user.

You might choose to use this function as the first step in a custom appointment booking solution. Steps 2 and 3 would be creation of a contact and creation of an appointment with that contact. If you require online booking functionality check out our pre-built booking system first which can be included into your website with a few lines of code and should suit most use cases.

Parameters

Field Type Description
days number Specifies the number of days in advance to return free slots for. Calculating appointmentSlots is computationally expensive, for best performance keep value for days as low as possible.
service_id string Returns appointments available for a particular service.

To explain further, take for example a clinic which might have a service for "walk-in x ray". This service may only be available wed mornings perhaps and maybe only 2 staff members can perform this service. Passing in the parameter for service_id will return a subset of free slots which take into account the users and resources available for the specified service. Also see Services
singleUser string By default free slots for all users are returned. If you wish to return free appointment slots for an individual user in a multiuser account you can specify the username here.


"GET on availableSlots" JSON response sample

{ "freeslots_by_user": [{ "user_id": "usr_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM", "available_timeslots": ["16|12|12|9|00", "16|12|12|13|00", "16|12|13|14|00", "16|12|14|9|00", "16|12|14|11|00"] }, { "user_id": "usr_90TUn1maaJzMH90Rqp1M0IFMoVEUGRUb", "available_timeslots": ["16|12|12|10|00", "16|12|14|13|00"] }], "users": [{ "id": "usr_90TU4BXMUV0T0ZHVNpVVDdWeN10VTRUM", "title": "User name1", "img": "https://www.yellowschedule.com/*url for profile image*" }, { "id": "usr_90TUn1maaJzMH90Rqp1M0IFMoVEUGRUb", "title": "User name2", "img": "https://www.yellowschedule.com/*url for profile image*" }] }


Response

Field Type Description
freeslots_by_user list list of free slot for users
user_id string id of the user
available_timeslots list simple listing of available timeslots for that user. Individual datetimes are in the format "yy|mm|dd|hh|mm" eg "16|12|13|14|30" which is 13th Dec 2016 at 2:30pm.
users list list of system users whom there maybe free slots for
id string user id - matches with "user_id" under "freeslots_by_user"
title string user name
img string url for profile image for the user
Contacts
URL Methods
https://www.yellowschedule.com/app/api/v2/contacts GET - show a specific contact or a listing of contacts
POST - create new contacts on the system
PUT - for updating a contact
DELETE - for deleting a contact

Function: Contacts (GET)

Description: Shows listing of an individual contact or a list of contacts.

Parameters

Field Type Description
contact_id string Returns a specific set of contact details by passing in contact_id.
user_id string Pass in a user_id if you wish to see expanded details for a particular user
search_field (*) string Used in conjunction with search_value below. You can search a particular (indexed) user defined custom field for a value. (Please contact us if you need this API function as we will need to setup search indexes for this field)
search_value (*) string Used in conjunction with search_field above. You can search a particular (indexed) user defined custom field for a value. (Please contact us if you need this API function as we will need to setup search indexes for this field)
page number Returned appointments may be broken into pages, requiring a page number to be passed in (see Pagination)


"GET on contacts" JSON response sample

/* simple example - very little being stored for contact 85800000 */ { "contacts": [{ "contact_id": "con_90TQycTbUpFRlFEduhXOrMFUyVkSOFHM", "created_utc": "2015-06-17 11:13:05", "edited_utc": null, "archived": 0, "firstname": "john", "lastname": "client" }], "paginginfo": ... }


/* complex example - more data for contact 85800001 plus data contained in user-defined fields: "Policy number" and "Blood Type" */ { "contacts": [{ "contact_id": "con_90TQEt0SyoWROp3VYNlWNNzSVFzSyVWW", "created_utc": "2016-06-20 20:31:22", "edited_utc": "2016-12-01 13:07:21", "archived": 0, "firstname": "clark", "lastname": "kent", "email": "clarkkent@test.com", "cellphone": "353879999999", "gender": "m", "dob": "2000-12-25", "notes": "open notes section for the client", "user_defined_fields": [{ "field_id": 10, "field_title": "Policy number", "value": "5480001200" }, { "field_id": 20, "field_title": "Blood Type", "value": "AB-" }] }], "user_defined_data_fields": [{ "datafield_id": "10", "datafield_title": "Policy number", "datafield_enabled": "0", "enabled_for_bookings": "0", "is_selectbox": "0" },{ "datafield_id": "20", "datafield_title": "Blood Type", "datafield_enabled": "1", "enabled_for_bookings": "0", "is_selectbox": "1", "selectbox_values": { "100": "A+", "101": "A-", "102": "AB+", "103": "AB-" } }], "paginginfo": ... }


Response

Field Type Description
contacts list Listing of the returned contacts
contact_id string Unique contact id (created by YellowSchedule)
created_utc datetime Datetime the contacts was created on the system in UTC timezone.
edited_utc datetime Datetime the contacts was last edited on the system in UTC timezone. Null if no edits have been made
archived boolean Contacts who have been archived with the system will show up as 1 (For active contacts this value will be 0).
firstname string Clients first name
lastname string Clients last name
email string Clients email address
cellphone string Cellphone number of the client including country code. Domestic formatting removed eg (541) 345-5555 = 15413455555.
gender string Character indicating clients Gender (m or f).
dob string Clients date of birth
notes string Notes section for the client. (There is also seperately a Note section for Appointments if it's required to keep notes seperately for individual appointments)
user_defined_fields list You can create entirely new datafields in YellowSchedule to store client data field types that we haven't even thought of yet!

More on customizable data fields
field_id number Id of the user defined datafield. These match with user_defined_data_fields.datafield_id (see below)
field_title string Field title of the user defined datafield.
value string Value of the user defined field. If the user defined text field was something like "Blood Type", this value field might be something like "AB-"
user_defined_data_fields list Full details of "user_defined_data_fields"
datafield_id number Unique id for the datafield(created by YellowSchedule)
datafield_title string Title of the user-defined data field
datafield_enabled boolean User-defined data fields can be disabled within YellowSchedule
enabled_for_bookings boolean Similar to above. User-defined data fields for clients can also be presented to the client within the YellowSchedule patient booking system (if it's used). As an example, if there's a custom data field with a title of perhaps "patient in distress?". Within YellowSchedule you could have this field enabled in the system and available to a clinician to set, but not included within the booking system so that it's never directly set by the client(patient) themselves.
is_selectbox boolean Value is 1 if the user-defined data field is a selectbox option with preselectable options
selectbox_values list Listing of user defined selectable options. Eg if the user-defined field is "Blood Type" for example the may be preentered selectable options with possible blood types. This lists available options in an id => value pair.
found_contact_ids (*) list of contact ids Listing of contact id return from an api search operation as defined by the search_field and search_value parameters above. If a search is performed using search_field and search_value params above the returned value "found_contact_ids" will be the only value return. If no search is perfomed "found_contact_ids" won't be present.

Function: Contacts (POST)

Description: Create a contact on YellowSchedule using the API.

Parameters

Field Type Description
user_id string Unique id of the user. Appointments created are assigned to a user and show on their calendar
firstname string Contact first name
lastname string Contact last name
email string Contact email address
cellphone string Contact phone number. Formatting is removed and it is converted into international format on our system eg a phone number string such as "(555) 1234-555" will be accepted and converted into internation format (+15551234555) in the background on our system.
landline string Contact phone number for landline. (No attempt is ever made to send text message reminders to "landline" phone numbers)
address string A single field stores the contact address. If your address data is multi-field (eg house number, streetname, postcode etc) then please concatinate the full address into the one field seperated with commas passing the address as a single string such as: "1234 main street, sunnydale, 90210".
birthdate string If used, date of birth should be entered in three parts. For example 12 june 1979 would be birthdate of "12", birthmonth of "6" and "birthyear" of "1979".
birthmonth string See description above for birthdate. birthmonth can be entered as a number 1-12 here.
birthyear string See description above for birthdate. birthyear is the year number such as 1979.
gender string If entered gender field can be either "m" or "f".
notes string Open notes field for storage of client notes
stripetoken string We are partnered with Stripe to allow storage of credit card details for contacts to allow online billing through YellowSchedule. Credit card details cannot be directly passed to our API but instead must be posted to Stripe who will reply with a stripe token. This Stripe token can then be passed to us. Please contact us for further support if you require online payment functionality through our API.


"POST on contacts" JSON response sample

{ "status":"success", "created_contact_id":"con_90TUspnNlV2YKV3MsVkSMl2VxljW4V3a" }


Response

Field Type Description
status string Success (or failure) message
created_contact_id string Unique id of the newly created contact

Additional note for setting contacts with custom data values

If you need to create (POST) or update (PUT) contacts and also need to set a custom data field for the contact then you can reference the field using custom_xxxx (where xxxx is a numeric field id). You can find the correct field id within the App by going to "Settings" (top right menu) >> "Contacts data fields" >> then click "Edit" beside the desired field. In light grey text beside the field title you will see the field key. See the screenshot below for an example where the field id for the additional field is custom_1534.

Custom data fields

If the custom field is a multiselect option you can pass in the id of an option value. This is done by passing in as a string as follows "optvalue_xxx" where xxx is a numeric value for the id of the option. For example if a custom field with a title such as "profession" has a field id of "custom_123456" containing pre-selectable options such as "Coder" and the option value for "Coder" is 56789 then the parameter would be "custom_123456":"optvalue_56789".


Function: Contacts (PUT)

Description: Update a contact on YellowSchedule using the API. Contacts can be updated sending only the param that you want to change. If you want to clear a specific field, send an empty string in the parameter.

Parameters

Field Type Description
contact_id string Unique contact id (created by YellowSchedule)
firstname string Contact first name
lastname string Contact last name
email string Contact email address
cellphone string Contact phone number. Formatting is removed and it is converted into international format on our system eg a phone number string such as "(555) 1234-555" will be accepted and converted into internation format (+15551234555) in the background on our system.
landline string Contact phone number for landline. (No attempt is ever made to send text message reminders to "landline" phone numbers)
address string A single field stores the contact address. If your address data is multi-field (eg house number, streetname, postcode etc) then please concatinate the full address into the one field seperated with commas passing the address as a single string such as: "1234 main street, sunnydale, 90210".
birthdate string If used, date of birth should be entered in three parts. For example 12 june 1979 would be birthdate of "12", birthmonth of "6" and "birthyear" of "1979".
birthmonth string See description above for birthdate. birthmonth can be entered as a number 1-12 here.
birthyear string See description above for birthdate. birthyear is the year number such as 1979.
gender string If entered gender field can be either "m" or "f".
notes string Open notes field for storage of client notes
archived number You can edit a contact through the API setting the value for archived to '1' or '-1'. Archiving a contact may be a good option to use in place of deleting a contact if you'd like to retain the contacts record details while taking the contact out of the active pool of contacts.
stripetoken string We are partnered with Stripe to allow storage of credit card details for contacts to allow online billing through YellowSchedule. Credit card details cannot be directly passed to our API but instead must be posted to Stripe who will reply with a stripe token. This Stripe token can then be passed to us. Please contact us for further support if you require online payment functionality through our API.

"PUT on contacts" JSON response sample

{ "status":"success", "updated_contact_id":"con_90TUspnNlV2YKV3MsVkSMl2VxljW4V3a" }


Response

Field Type Description
status string Success (or failure) message
updated_contact_id string Unique id of updated contact

Function: Contacts (DELETE)

Description: Delete a contact on YellowSchedule using the API.

Parameters

Field Type Description
contact_id string Unique contact id (created by YellowSchedule)

"DELETE on contacts" JSON response sample

{ "status":"success", "deleted_contact_id":"con_90TUspnNlV2YKV3MsVkSMl2VxljW4V3a" }


Response

Field Type Description
status string Success (or failure) message
deleted_contact_id string Unique id of deleted contact
Services
URL Methods
https://www.yellowschedule.com/app/api/v2/services GET - show listing of services

Function: Services (GET)

Description: Shows listing of services. When appointments are created a service can be set. Services are user defined and may be something like "Initial consultation" or "x-ray" for example. A price and time length can be set for the service when it's created allowing for easily scheduling of services and payment of services (if client payments are used). At present there is only GET method available to view services and services currently need to be created/edited/deleted within the YellowSchedule Application.

Parameters

Field Type Description
service_id string Specify the service_id to get details of that service
user_id string Specify the user_id to only show services for that particular user


"GET on services" JSON response sample

[{ "service_id": "ser_90TUspnNlV2YKV3MsVkSMl2VxljW4V3a", "title": "initial consultation 30 minutes", "shorttitle": "initial 30m", "length": "30", "price": "$100", "users_with_access_to_service":[ {"user_id":"usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY"}, {"user_id":"usr_90TUn1maaJzMH90Rqp1M0IFMoVEUGRUb", "restrictions":["mo|09:00:00-13:00:00","tu|09:00:00-13:00:00"]} ] },{ "service_id": ... }]


Response

Field Type Description
service_id string Unique id of the service
title string Description of the service
shorttitle string Short desc of above
length number Length of service duration in minutes
price string Price of service
users_with_access_to_service list Listing of the users who are able or qualified to administer this service
user_id string Id of a user with ability to perform this service
restrictions list If 'restrictions' are present this field indicate that the service has partial availability for the user listed in the user_id above.

If present this field will be a listing of strings (pipes) containing the day of week and time range the service is avail. Example "tu|09:00:00-19:00:00" indicates this service has been made only available on Tuesdays from 9am - 7pm. This can be a listing of pipes and in the JSON response example above you can see:
"users_with_access_to_service":[{
	"user_id":"usr_90TUn1maaJzMH90Rqp1M0IFMoVEUGRUb",
	"restrictions":[
		"mo|09:00:00-13:00:00","tu|09:00:00-13:00:00"
	]}]

This means the listed service 'initial consulation 30 minutes' may be available to the user identified by user_id=usr_90TUn1maaJzMH90Rqp1M0IFMoVEUGRUb only on mondays and tuesdays 9am-1pm. Administration of user-services is within the Application only ("Settings" >> "Online Booking Setup" >> "Select User" >> "Services" >> Restrictions "Edit").
Users
URL Methods
https://www.yellowschedule.com/app/api/v2/users GET - show listing of users

Function: Users (GET)

Description: Shows listing of user (staff) details. Add/edit/delete operations on system users must be performed within YellowSchedule at present.

Parameters

Field Type Description
user_id string Pass in a user_id if you wish to see expanded details for a particular user


"GET on users" JSON response sample

[{ "user_id": "usr_90zdhlGRJtCSxJkVEV2TYNzNxl1UrkmY", "created_utc": "2015-07-14 15:24:23", "firstname": "John", "lastname": "Doe", "username": "johndoe", "display_name": "Dr. John Doe", "email": "johndoe@johndoe.com", "img": "https://www.yellowschedule.com/*url for profile image*", "admin": "1", "access_all_contacts": "1", "access_all_msgs": "1", "booking_enabled": "1" },{ "user_id":... }]


Response

Field Type Description
user_id string Unique id of the User.
created_utc datetime Datetime the user was created on the system in UTC timezone.
firstname string Users first name
lastname string Users lastname
username string User username that they will use for logging in
display_name string A display name for the user
email string Email address of the user
img string Url to a profile image of the user
admin boolean Does the user have administator capabilities (0 or 1)
access_all_contacts boolean Does user have access to view contact details for contacts created by other users (0 or 1)
access_all_msgs boolean Does user have access to view all messages sent and received for contacts created by other users (0 or 1)
booking_enabled boolean Is online booking functionality switched on for this user (0 or 1)