Important changes
Migrating from the legacy API requires a full re-evaluation of existing API and webhook integrations as every endpoint will require some change. To guide you, we are listing some of the most important changes.
OAuth 2.0 standardization
All authentication interaction has been fully standardized towards OAuth 2.0.
Removed support for custom grant types
The following custom grant types are no longer supported and have not been replaced:
office365_codepublic_clientpublic_client_passwordresource_codesaml
Only the client_credentials grant type is supported, which was already and is still compliant to OAuth 2.0.
Removed support for application/json content type in access token request
As specified by the OAuth 2.0 specification, the content type for the access token request must be application/x-www-form-urlencoded. The application/json is no longer be allowed.
Optional scopes
When requesting an access token, the desired scopes must always be provided. By default, the scopes will be empty unlike before.
Removed /identity endpoint
The /identity endpoint to retrieve information about the current access token has been removed. Access tokens are now valid JSON Web Tokens (JWTs) and thus contain all information in an encoded form.
Removed support for request content types other than application/json
Except for OAuth 2.0 requests, all requests should use application/json as content type. The content types multipart/form-data and x-www-form-urlencoded are no longer supported.
Changed casing conventions
Path and query parameters in URLs will consistently follow a kebab-case naming convention.
Request and response bodies will consistently contain JSON-structured data where property names follow a camelCase naming convention.
external-id properties are now case-sensitive. This should be taken into account when querying the API but also when creating plugin configurations.
Changed pagination mechanism and parameters
Pagination is applied by default rather than on-demand.
The query parameters to control the mechanism have also been modified to require a record offset instead (offset) of a page index (page). The per_page query parameters has been renamed to limit.
The meta object in the response body has also been restructured. The old meta object properties can be derived from the new ones as follows:
total=totalCountper_page=limitcurrent_page= (offset/limit)+1, assumingoffsetis a multiple oflimitlast_page= ceiling(totalCount/limit)from=offset+1to=offset+limit
See also Pagination.
Removed support for some array query parameter syntax
The syntax for passing array query parameters in requests has changed.
Specifically, the syntax name=value is no longer supported for array query parameters.
See also Array query parameters.
Removed enterprise_id references
The enterprise_id references have been removed from all request and response bodies as the enterprise is implied by the URL.
Changed translatable resource mechanisms
The data structure for returning translatable resources has been changed. Apart from how the translated data is returned, also when data is returned has been changed. Translatable resources will always be returned, regardless of whether translations exist for the requested language, unlike before where translatable resources would not be returned if no translations exist for the requested language. Instead, the translatable properties of the resource are returned as null if no translation exists for the requested language.
The data structure for managing translatable resources has been changed. Translated data is now always explicitly passed together with the language of the translation, unlike deriving it from the Content-Language header, which is no longer used.
There is no requirement to have a translation for a resource available in the default enterprise language anymore. When * is passed in the Accept-Language header value, the system will first try to find a translation for the default enterprise language but will then return any translation that exists if no translation is available for the default enterprise language.
Translations will always be returned for a property if they match the requested language, independent of whether other properties have translations for the same language. The "fully translated" concept therefore no longer exists.
Also see Translatable resources and the request and response bodies for translatable resources, as documented here.
Changed location structure
Locations are now translatable, allowing to define specific parts of an address in multiple languages.
The postal code and geolocation (coordinates) components of locations have also been made optional, unlike before. In case no geolocation component is provided, it is automatically calculated by the system.
Removed include query parameter for all endpoints
The possibility to include related resources when requesting one or multiple resources, using the include query parameter has been removed. A number of endpoints now return some of the content, that could be explicitly included before, by default. Other inclusion possibilities require separate additional API calls.
Replaced subject questions, outcome lists, cancellation reasons, appointment answers and outcome remarks with forms
It is now possible to build highly-customizable forms that can be linked to subjects for use as a questionnaire during appointment creation, appointment cancellation and appointment completion. This replaces the old subject questions, outcome (lists) and cancellation reasons.
Although the same features (and more) are still available using the forms, it is recommended to thoroughly investigate the new endpoints to see how old API calls can be translated into new ones.
Availability template model changes
The explicit differentiation between day and week templates has been replaced with a general availability template concept where each availability template has a type, indicating whether it is a day or week template.
Removed endpoints
The /contacts/:contact_id/day_templates and /contacts/:contact_id/week_templates endpoints have therefore been replaced with the Availability templates endpoints.
Time zones for availability templates
Availability templates now have a time zone property. This is the time zone that should be used to interpret the time ranges defined in the availability template when it is applied on a specific day. Before, the time zone that was used to interpret the time ranges was the time zone of each office assigned to the time range.
As an example: a time range from 09:00-12:00 linked to both the Brussels and London offices would result in availability from 09:00-12:00 in Brussels and also 09:00-12:00 in London time zone when applying it on a specific day, resulting in a total availability of 4 hours. This will no longer be the case as the reference time zone on the availability template will be used instead, resulting in a total availability of 3 hours.
Removed 'special' unavailability day template
See user-defined unavailability
Default template property
The default template for a specific employee can now be derived from an isDefault property on the availability templates.
Time range availability settings structure
The interface of the availability settings related to a specific time range has changed. The related availability settings now contain a full view including potential subject-specific overrides. They are always stored using a single PUT request rather than a combination of POST, PATCH and DELETE requests.
Note that the auto_accept property has been replaced by a forceManualAccept property and that the meaning differs slightly. The auto_accept property could either be null or false, which translated to the forceManualAccept property being false or true respectively.
Also the uses_subject_specific_settings property has been renamed to overridesDefault.
Appointment model changes
Removed properties
The following appointment properties have been removed without replacement:
uuidis_success
The customer_showed appointment property has been removed in favor of a newly added NO_SHOW appointment status which can be set by setting noShow to true in the Complete appointment request.
The occurred appointment state has been removed but can still be derived by checking whether the appointment status is ACCEPTED/COMPLETED and the appointment end timestamp is in the past.
The cancelled_by_* appointment properties have been removed without replacement. In the near future, it will become possible to request appointment history information however. This will contain the cancellation audit information.
Removed appointment possibilities
The appointment model has been simplified by removing the concept of "appointment possibilities". All information that was previously stored on the possibility level is now stored on the appointment itself.
Additional participants for appointments
Appointments now allow to specify multiple employee participants and multiple customer participants, unlike the one-to-one appointment before. One-to-one appointments should therefore now be created as an appointment with two participants: one having type EMPLOYEE and role PRIMARY and another one having type CUSTOMER and role PRIMARY.
Separate endpoints for appointment operations
Specific appointment operations, such as cancelling, completing and rescheduling appointments, should now be done using simple and intuitive endpoints rather than having to perform a generic update on some specific appointment properties to achieve the desired result.
Removed audit modification
The possibility to set the initiator and modifier audit information on appointments has been removed and will be automatically determined from now on.
Removed scheduling rules bypass
The possibility to bypass specific scheduling rules while creating/rescheduling/reassigning appointments has been removed. The scheduling rules that should be applied will be automatically determined from now on, based on the user performing the operation.
Removed appointment deletion endpoint
The endpoint to delete an appointment has been removed without replacement. Appointments should instead always be cancelled instead.
Removed available contacts endpoint
The /appointments/:appointment_id/available_contacts endpoint has been removed without replacement. The /defined-availability and /timetable endpoints should be used instead to determine employee availability at the time of the appointment.
Removed calendar links endpoint
The /appointments/:appointment_id/calendar_links endpoint has been replaced with the Calendar event endpoints.
Removed messages endpoint
The /appointments/:appointment_id/messages endpoints have been removed. Transient operation-related messages should now be passed as part of the specific operation requests instead.
Defined availability changes
Removed location query parameters
The location query parameters have been removed as they are not relevant anymore for calculating defined availability. They were necessary to take into account region coverage limitations but this was deemed to be too complex. Instead, region coverage limitations are now not taken into account when calculating defined availability.
Removed properties
The estimated_duration, granularity, time_slot_granularity time_slot_earliest_possible, time_slot_latest_possible and trailing_buffer_time properties have been removed from the defined availability response as they are only relevant for timetable calculation but not for defined availability.
Employee model changes
Merged contact, admin, office manager, central planner, employee and user resources
The contact, admin, office manager, central planner, employee and user resources have been merged into a single employee resource.
The roles assigned to an employee are to be found in the availableRoles property and depending on the role, some other role-specific properties will be set.
Removed properties
The following employee properties have been removed without replacement:
user.genderuser.date_of_birthadmin.is_ownercontact.introduction
The contact.is_active property has been renamed to onlinePlanning.
Removed endpoints
The following endpoints have been removed without replacement:
/users/:user_id/calendars/users/:user_id/sync_accounts/users/:user_id(activation)/employee_activations
Removed possibility to set password for user on creation
It is no longer possible to set a password for a user through the API. Instead, a user should set its own password using an invitation link which the system will send.
Translatable employee function
The function property for employees with the AGENT role is now translatable.
Changed process for uploading profile picture
The process for uploading a profile picture for an employee has been changed and now requires two steps. See File uploading.
Customer model changes
Removed properties
The following customer properties have been removed without replacement:
preferred_office_idpreferred_contact_idgenderdate_of_birthprofile_picture
Removed endpoints
The following endpoints have been removed without replacement:
/customers/:customer_id/profile_pictures
Enterprise and settings model changes
Removed enterprise resource
The enterprise resource does not exist on its own anymore. All enterprise information, the logo and settings have been merged into a single /settings endpoint.
Removed endpoints
The following endpoints have been removed without replacement:
/enterprises/enterprises/:enterprise_id/enterprise_messages
Lead segment model changes
Scheduling settings
The /lead_segment_subjects endpoint, which allows to specify allowed subject and meeting type combinations for a lead segment has been replaced by the /lead-segments/:id/scheduling-settings endpoint.
Removed properties
The is_preferred property has been removed from the lead segment scheduling settings structure without replacement.
Office model changes
Scheduling and availability settings
The /offices/:office_id/subject_availability_settings endpoint, which allows to specify allowed subject and meeting type combinations and their respective availability settings for an office has been replaced by the /offices/{id}/subject-scheduling-settings endpoint and the /offices/{id}/subject-availability-settings endpoint.
Renamed properties
The title property has been renamed to name for consistency purposes.
Translatable properties
The following properties are now translatable:
namedescriptiondirectionsparkingInfo
Subject model changes
Scheduling and availability settings
The /subjects/:subject_id/availability_settings endpoint, which allows to specify allowed meeting types and their respective availability settings for a subject has been replaced by the /subjects/{id}/scheduling-settings endpoint and the /subjects/:id/availability-settings endpoint.
Renamed models and properties
The title property for subjects has been renamed to name for consistency purposes.
The is_shortlist property for subjects has been renamed to enabledForCustomerUse for clarity purposes.
The Subject Category concept has been renamed to Subject Group.
Removed properties
The following subject properties have been removed without replacement:
is_activeis_defaulttimezone
Support members
The concept of support members has been removed without replacement.
Timetable changes
Removed postal code and country location query parameters
It is not longer possible to pass a location to the timetable endpoint using postal code and country. Coordinates should be used instead.
Removed properties
The max_concurrent_appointments and scheduled_concurrent_appointments have been removed from timetable response without replacement.
Added contextual information
Next to the actual time slots, the timetable endpoint now also returns information about the duration, earliest and latest possible time slot. This information can be used when making timetable calls to know the range in which time slots can be offered.
Unavailability changes
Removed query parameters
The offices, subjects, format[timezone] and ignore_skedify_appointments query parameters have been removed without replacement.
Removed context
The context of each specific unavailability will not be returned in the response anymore. Only the type, start and end time will be returned, together with an optional external ID.
User-defined unavailability
A new concept has been added, called user-defined unavailability. This is a replacement for what used to be a 'special' day template, allowing to introduce days of unavailability. User-defined availability can be created for a specific employee on specific dates and can also be removed again. This is similar to applying the 'special' day template for a specific employee on specific days in the legacy.
Webhook configuration changes
The possibility to configure a webhook to use a specific client certificate when making requests has been removed.
This was typically used for certificate pinning is recommended against by Pexip to avoid complications with your integration when we roll out new certificates for our systems.
DigiCert, one of the major CAs, also recommends against certificate pinning.
Migration assistance
Although this documentation should already answer a lot of questions, we understand that you might have some additional questions or would like some advice. Contact your account manager to request advice from one of our experts.