logo
Documentation Powered by ReDoc

Appointedd Public API (1.0.0)

Download OpenAPI specification:Download

License: UNLICENSED

Authentication

X-API-KEY

All requests to this API need to be authenticated by your Appointedd organisation's API key.

You can find this on the API Settings page on your Appointedd web application.

Security scheme type: API Key
Header parameter name: X-API-KEY

Introduction

Welcome to Appointedd's public facing API! Here you'll find reference documentation for our API routes.

Pagination

Routes that return multiple objects in this API are paginated.

These routes will always return a response with the following properties:

  • data - Array of objects that are on this page.
  • total - Total number of objects that could be returned, including those on this page.
  • next - ID of the first object on the next page.
  • prev - ID of the last object on the previous page.

These routes will also have a way to specify which page to return. These properties will be called start and end, and will either be accepted in the query parameters or the payload depending on the method of the route.

  • To navigate forward a page, simply supply the ID in the next property of the current page to the start parameter of the route.
  • To navigate backward a page, simply supply the ID in the prev property of the current page to the end parameter of the route.

Availability

Endpoint that allows you to perform search operations for the availability of resources in your Appointedd organisation.

Search available intervals

Find intervals that are available for one or more resources assigned to a service in your Appointedd organisation.

The maximum number of days (in total and non-continuous) in the ranges is currently 42 days.

Authorizations:
X-API-KEY
Request Body schema: application/json
ranges
required
Array of Intervals (objects) or Array of Dates (strings)

Range of intervals of time or dates of days to query availability for.

service_id
string <object-id>

ID of a service in your organisation.

If specified the following will be loaded from the service and used in the availability query:

  • Service Schedule (Unless ignore_service_schedule is set to true)
  • Assets
  • Buffers
resource_ids
Array of strings <object-id>

IDs of resources to query availability for.

resource_group_ids
Array of strings <object-id>

IDs of resource groups to query availability for.

buffers
object

Booking buffers control the amount of time before and/or after a booking that must not contain any other bookings, breaks, or external events. If you do not specify any buffers then they will either be loaded from a service if you have given one, or default to query with no buffers.

duration
integer >= 1

The number of continuous minutes of time from the start of an interval that must be free for an interval to be considered available.

If you do not specify the parts property or this property, and you have specified a service property, the default duration or parts for that service will be used.

If you specify the parts property in this request this property will be ignored.

parts
Array of objects
increment
integer [ 1 .. 60 ]
spaces
integer >= 1
Default: 1

Number of spaces that are required. This is used to exclude any group bookings that do not have enough spaces.

timezone
string <iana-zone>
Default: "Europe/London"

The IANA timezone that the input date & time ranges will be treated as when querying for availability. The returned intervals will also be in this timezone.

ignore_past_restriction
boolean
Default: false

If set to true availability will not be restricted by the current date and time.

By default this is set to false and any date and time before the current date and time will be considered as unavailable.

ignore_notice_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's notice period settings.

By default this is set to false and any date and time before the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_block_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's block period settings.

By default this is set to false and any date and time after the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_bookings
Array of strings <object-id> (Booking ID)

Array of booking IDs in your organisation to ignore for the purposes of this availability query. This means that it will not block availability and if it is a group booking it will not be returned if it is available.

ignore_service_assignment
boolean
Default: false

If set to true, the request will not fail if the resource on this booking is not assigned to the service on this booking.

ignore_service_schedule
boolean
Default: false

If set to true availability will not be restricted by the service's schedule.

By default this is set to false and any date and time outside of the service's schedule will be considered as unavailable.

ignore_group_setting
boolean
Default: false

If set to true the availability will return bookings that have enough space as group bookings, regardless if they have online group bookings turned on.

shallow
boolean
Default: false

If set to true then only the date & time of each available interval is returned; any additional data will be omitted.

Responses

200

Successfully found availability

post /availability/intervals/search
https://api.appointedd.com/v1/availability/intervals/search

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "ranges":
    [
    ],
  • "service_id": "string",
  • "resource_ids":
    [
    ],
  • "resource_group_ids":
    [
    ],
  • "buffers":
    {
    },
  • "duration": 1,
  • "parts":
    [
    ],
  • "increment": 1,
  • "spaces": 1,
  • "timezone": "Europe/London",
  • "ignore_past_restriction": false,
  • "ignore_notice_restriction": false,
  • "ignore_block_restriction": false,
  • "ignore_bookings":
    [
    ],
  • "ignore_service_assignment": false,
  • "ignore_service_schedule": false,
  • "ignore_group_setting": false,
  • "shallow": false
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    [
    ]
}

Search available dates

Find the dates that a resource is available in your Appointedd organisation.

The maximum number of days (in total and non-continuous) in the ranges is currently 42 days.

Authorizations:
X-API-KEY
Request Body schema: application/json
ranges
required
Array of Ranges (objects) or Array of Dates (strings)

Range of intervals of time or dates of days to query availability for.

service_id
string <object-id>

ID of a service in your organisation.

If specified the following will be loaded from the service and used in the availability query:

  • Service Schedule (Unless ignore_service_schedule is set to true)
  • Assets
  • Buffers
resource_ids
Array of strings <object-id>

IDs of resources to query availability for.

resource_group_ids
Array of strings <object-id>

IDs of resource groups to query availability for.

duration
integer >= 1

The number of continuous minutes of time from the start of an interval that must be free for an interval to be considered available.

If you do not specify the parts property or this property, and you have specified a service property, the default duration or parts for that service will be used.

If you specify the parts property in this request this property will be ignored.

parts
Array of objects non-empty

Parts are used to specify spans of time which must be available for an interval to be considered as available. The first part must always be a part of type "block".

increment
integer [ 1 .. 60 ]
spaces
integer >= 1
Default: 1

Number of spaces that are required. This is used to exclude any group bookings that do not have enough spaces.

timezone
string <iana-zone>
Default: "Europe/London"

The IANA timezone that the input date & time ranges will be treated as when querying for availability. The returned intervals will also be in this timezone.

ignore_past_restriction
boolean
Default: false

If set to true availability will not be restricted by the current date and time.

By default this is set to false and any date and time before the current date and time will be considered as unavailable.

ignore_notice_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's notice period settings.

By default this is set to false and any date and time before the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_block_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's block period settings.

By default this is set to false and any date and time after the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_bookings
Array of strings <object-id> (Booking ID)

Array of booking IDs in your organisation to ignore for the purposes of this availability query. This means that it will not block availability and if it is a group booking it will not be returned if it is available.

ignore_service_assignment
boolean
Default: false

If set to true, the request will not fail if the resource on this booking is not assigned to the service on this booking.

ignore_service_schedule
boolean
Default: false

If set to true availability will not be restricted by the service's schedule.

By default this is set to false and any date and time outside of the service's schedule will be considered as unavailable.

ignore_group_setting
boolean
Default: false

If set to true the availability will return bookings that have enough space as group bookings, regardless if they have online group bookings turned on.

shallow
boolean
Default: false

If set to true then only the available date is returned; any additional data will be omitted.

Responses

200

Successfully found availability

post /availability/days/search
https://api.appointedd.com/v1/availability/days/search

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "ranges":
    [
    ],
  • "service_id": "string",
  • "resource_ids":
    [
    ],
  • "resource_group_ids":
    [
    ],
  • "duration": 1,
  • "parts":
    [
    ],
  • "increment": 1,
  • "spaces": 1,
  • "timezone": "Europe/London",
  • "ignore_past_restriction": false,
  • "ignore_notice_restriction": false,
  • "ignore_block_restriction": false,
  • "ignore_bookings":
    [
    ],
  • "ignore_service_assignment": false,
  • "ignore_service_schedule": false,
  • "ignore_group_setting": false,
  • "shallow": false
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    [
    ]
}

Availability Slots

Endpoint that allows you to perform create/read/delete operations for availability slots in your Appointedd organisation.

Create an availability slot

Create a new availability slot reservation in your organisation, which reserves an interval of time of a resource until it expires, and can be used to create a new booking. If there is either a slot reservation that is available to other slot reservations (has allow_additional_spaces set to true) or there is an existing group booking at the date and time that you are trying to create a slot, it will instead return a reservation for spaces on that slot reservavtion/group booking.

Authorizations:
X-API-KEY
Request Body schema: application/json
ignore_past_restriction
boolean
Default: false

If set to true availability will not be restricted by the current date and time.

By default this is set to false and any date and time before the current date and time will be considered as unavailable.

ignore_notice_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's notice period settings.

By default this is set to false and any date and time before the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_block_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's block period settings.

By default this is set to false and any date and time after the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_service_schedule
boolean
Default: false

If set to true availability will not be restricted by the service's schedule.

By default this is set to false and any date and time outside of the service's schedule will be considered as unavailable.

increment
integer
data
required
Reservation (object) or Recurring Group Reservation (object)

Responses

201

Successfully created an availability slot

post /availability/slots
https://api.appointedd.com/v1/availability/slots

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "ignore_past_restriction": false,
  • "ignore_notice_restriction": false,
  • "ignore_block_restriction": false,
  • "ignore_service_schedule": false,
  • "increment": 0,
  • "data":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    {
    }
}

Get availability slots

Retrieves the availability slots in your organisation with pagination.

Authorizations:
X-API-KEY
query Parameters
limit
integer [ 1 .. 100 ]

The number of objects to return per page.

start
string <object-id>

The ID of the object at the start of the next page.

end
string <object-id>

The ID of the object at the end of the previous page.

sort_by
string
Enum:"natural" "created" "updated" "start"

Property to use to sort the returned availability slots.

order_by
string
Default: "descending"
Enum:"asc" "ascending" "desc" "descending"

Direction to order the returned availability slots.

before
string <date-time>

Filters the returned availability slots by the date and time they end at (including the after buffer), returning only those that end at or before this date and time.

after
string <date-time>

Filters the returned availability slots by the date and time they start on (including the before buffer), returning only those that start on or after this date and time.

Responses

200

Successfully retrieved availability slots

get /availability/slots
https://api.appointedd.com/v1/availability/slots

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    [
    ]
}

Delete availability slot by ID

Delete an existing availability slot in your organisation.

Authorizations:
X-API-KEY
path Parameters
slot_id
required
string <object-id>

ID of the availability slot to delete.

Responses

204

Successfully deleted an availability slot.

delete /availability/slots/{slot_id}
https://api.appointedd.com/v1/availability/slots/{slot_id}

Retrieve availability slot by ID

Returns an existing, unexpired availability slot in your organisation.

Authorizations:
X-API-KEY
path Parameters
slot_id
required
string <object-id>

ID of the availability slot to retrieve.

query Parameters
timezone
string
Default: "UTC"

IANA Timezone that will be applied to the dates & times in the response.

Responses

201

Successfully retrieved availability slot in your organisation.

404

Failed to retrieve availability slot in your organisation because it doesn't exist.

422

Failed to retrieve availability slot in your organisation because it has already expired.

get /availability/slots/{slot_id}
https://api.appointedd.com/v1/availability/slots/{slot_id}

Bookings

Endpoint that allows you to perform create/read/update/delete operations for bookings in your Appointedd organisation.

Create a new booking

Create a new booking in your organisation by using a previously created availability slot. If the availability slot reservation that is given in slot_id is an existing availability slot reservation that allows multiple reservations (has allow_additional_spaces set to true) then a new group booking is created any other remaining reservations will point automatically to the new group booking. If the availability slot reservation that is given in slot_id is an existing group booking then a new booking will not be created, instead the customers listed in this request will be added to that existing group booking.

Authorizations:
X-API-KEY
Request Body schema: application/json
slot_id
required
string <object-id>

ID of an availability slot to use to create this booking.

send_payment_request
boolean
Default: true

If set to true a payment request will be sent to each customer on this booking.

If not set, this will default to true.

timezone
string <iana-zone>
Default: "UTC"

The timezone to return the date and time properties on the booking as.

ignore_past_restriction
boolean
Default: false

If set to true availability will not be restricted by the current date and time.

By default this is set to false and any date and time before the current date and time will be considered as unavailable.

ignore_notice_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's notice period settings.

By default this is set to false and any date and time before the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_block_restriction
boolean
Default: false

If set to true availability will not be restricted by your organisation's block period settings.

By default this is set to false and any date and time after the number of minutes/hours/days added onto the current date and time will be considered as unavailable.

ignore_service_schedule
boolean
Default: false

If set to true availability will not be restricted by the service's schedule.

By default this is set to false and any date and time outside of the service's schedule will be considered as unavailable.

data
required
object (Booking)

Responses

201

Successfully created a new booking

post /bookings
https://api.appointedd.com/v1/bookings

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "slot_id": "5b0d7abd03de7d796dcc50e5",
  • "send_payment_request": true,
  • "timezone": "UTC",
  • "ignore_past_restriction": false,
  • "ignore_notice_restriction": false,
  • "ignore_block_restriction": false,
  • "ignore_service_schedule": false,
  • "data":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    {
    }
}

Get bookings

Retrieves the bookings in your organisation with pagination.

Authorizations:
X-API-KEY
query Parameters
limit
integer [ 1 .. 100 ]

The number of objects to return per page.

start
string <object-id>

The ID of the object at the start of the next page.

end
string <object-id>

The ID of the object at the end of the previous page.

sort_by
string
Enum:"natural" "created" "updated" "start"

Property to use to sort the returned bookings.

order_by
string
Default: "descending"
Enum:"asc" "ascending" "desc" "descending"

Direction to order the returned bookings.

before
string <date-time>

Filters the returned bookings by the date and time they end at (including the after buffer), returning only those that end at or before this date and time.

after
string <date-time>

Filters the returned bookings by the date and time they start on (including the after buffer), returning only those that start on or after this date and time.

created_before
string <date-time>

Filters the returned bookings by the date and time they were created on, returning only those that were created on or before this date and time.

created_after
string <date-time>

Filters the returned bookings by the date and time they were created on, returning only those that were created on or after this date and time.

updated_before
string <date-time>

Filters the returned bookings by the date and time they were last updated on, returning only those that were last updated on or before this date and time.

updated_after
string <date-time>

Filters the returned bookings by the date and time they were last updated on, returning only those that were last updated on or after this date and time.

ids
Array of strings <object-id> (Booking ID)

Filters the returned bookings by booking IDs, returning only those that have an ID that match at least one of the booking IDs here.

categories
Category ID (string) or Array of Catagory IDs (strings)

Filters the returned bookings by service category IDs, returning only those that have a service which is assigned to a category that matches one of the category IDs here. Supports both a single category ID or an array of category IDs.

services
Service ID (string) or Array of Service IDs (strings)

Filters the returned bookings by service IDs, returning only those that have a service ID that matches one of the service IDs here. Supports both a single service ID or an array of service IDs.

resources
Resource ID (string) or Array of Resource IDs (strings)

Filters the returned bookings by resource IDs, returning only those that have a resource ID that matches one of the resource IDs here. Supports both a single resource ID or an array of resource IDs.

resource_groups
Resource Group ID (string) or Array of Resource Group IDs (strings)

Filters the returned bookings by resource group IDs, returning only those that have a resource that is assigned to a resource group that matches one of the resource group IDs here. Supports both a single resource group ID or an array of resource group IDs.

customers
Customer ID (string) or Array of Customer IDs (strings)

Filters the returned bookings by customer IDs, returning only those that have a customer ID that matches one of the customer IDs here. Supports both a single customer ID or an array of customer IDs.

timezone
string <iana-zone> (IANA Timezone)

A valid, non-deprecated, IANA Timezone. Any property which is formatted as a date and time will be returned in this timezone.

statuses
Status (string) or Array of Statuses (strings)

Filters the returned bookings by status, returning only those that have a status that matches at least one of the provided statuses'.

Responses

200

Successfully retrieved your bookings

get /bookings
https://api.appointedd.com/v1/bookings

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    [
    ],
  • "total": 1,
  • "next": null,
  • "prev": null
}

Update a booking by ID

Update an existing booking in your organisation by its ID. If this modifies the start/end time of the booking an availability check will be performed.

Authorizations:
X-API-KEY
path Parameters
booking_id
required
string <object-id>

ID of the booking to update.

Request Body schema: application/json
ignore_service_assignment
boolean
Default: false

If set to true, the request will not fail if the resource on this booking is not assigned to the service on this booking when moving it. This however does not allow you to assign this booking to a resource to a service that is not assigned to it.

ignore_service_schedule
boolean
Default: false

If set to true, the availability check triggered on moving the booking will ignore the service's schedule. By default this is set to false and you will not be able to move the booking outside of the service's schedule.

increment
number [ 1 .. 60 ]
Default: 15

Increment to use when querying for availability if the booking's start/end buffers and/or part(s) have changed.

send_notifications
boolean
Default: true

If set to true a notification email will be sent to each customer on this booking indicating that this booking has been modified.

If not set, this will default to true.

timezone
string <iana-zone>

Timezone that any dates and times in the response object will be converted to. By default dates and times are returned in UTC (+00:00).

response_timezone
string <iana-zone>

Timezone that any dates and times in the response object will be converted to. By default dates and times are returned in UTC (+00:00). Alias of 'timezone' for backwards compatibility.

data
required
object

Responses

200

Successfully updated a booking

put /bookings/{booking_id}
https://api.appointedd.com/v1/bookings/{booking_id}

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "ignore_service_assignment": false,
  • "ignore_service_schedule": false,
  • "increment": 15,
  • "send_notifications": true,
  • "timezone": "string",
  • "response_timezone": "string",
  • "data":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    {
    }
}

Cancel an existing booking

Cancels an existing booking in your organisation by its ID.

Authorizations:
X-API-KEY
path Parameters
booking_id
required
string <object-id>

ID of the booking to cancel.

Request Body schema: application/json
source
string non-empty
Default: "api"

The name of the source that will be recorded as cancelling this booking.

Responses

204

Successfully cancelled a booking.

post /bookings/{booking_id}/cancel
https://api.appointedd.com/v1/bookings/{booking_id}/cancel

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "source": "api"
}

Update a customer on a booking by ID

Update a customer on an existing booking by the booking's ID and the customer's ID. Any property that you do not specify when updating a customer on this booking will retain the existing value, or will remain undefined if it did not have an existing value.

Authorizations:
X-API-KEY
path Parameters
booking_id
required
string <object-id>

ID of the booking that the customer is on to update.

customer_id
required
string <object-id>

ID of the customer on the booking to update.

Request Body schema: application/json
data
object

Responses

200
put /bookings/{booking_id}/customers/{customer_id}