> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sonderplan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Booking
>
`WRITE` access to the `SCHEDULE` module is required to access this endpoint
The `bookingEdited` webhook will be fired when this endpoint has run successfullyTo avoid generating lots of undesired notifications, take care when creating or updating bookings and consider using the `notify_user_resources` option which can be used to silence notifications for end users.
## OpenAPI
````yaml /api-reference/openapi-mintlify.yaml put /v2/booking
openapi: 3.0.0
info:
title: Sonderplan API
description: >
## Overview
You can use our REST API to securely access and modify the data within your
Sonderplan account. This includes all the information within your bookings,
projects and invoices that you can use to import / export data or create
integrations with other systems and software that you use
### General Notes
#### Specifying Fields
The Sonderplan REST API allows you to specify a comma delimited string of
exactly which fields are returned, using the `fields` parameter. Using this
parameter has several advantages including:
1. In future API versions we may change which fields are presented by
default, so explicitly specifying the fields required overrides the defaults
and ensure the fields are served
2. Limiting fields reduces the processing we need to do and allows us to
send you the data faster
3. Some search filters only work if the field you are searching is added to
the `fields` parameter.
Example:
```
fields=id,name,start,duration_min
```
### Applying Filters
The Query Parameters section in each endpoint shows you special options that
can be added to your request to customise the response we send you.
Most endpoints offer the following query params:
| Query Parameter |
Description |
|-----------------|----------------------------------------------------------------|
| `fields` | Only send the specified
fields |
| `id` | Specify one or more ids (comma seperated) of records to
return |
| `limit` | The maximum number of records to
return |
| `page` | The page number of records to
return |
| `order_asc` | Specify which field should be used to sort records
`ascending` |
| `order_desc` | Specify which field should be used to sort records
`descending` |
In addition to the standard `id` param, you can also specify most other
fields as a query parameter, useful for performing searching and filtering
of records.
For example, you can specify `repeat_master_id=` to
return all repeat children of that booking.
#### Other Query Params
Refer to the specific API endpoint documentation to see which other query
params can be used.
For example, some endpoints allow specifying `updated_after=` which will only send added, edited and even deleted records that
were modified after the unix timestamp.
#### Applying multiple filters
By default, multiple filters are chained together using **OR** (either
filter can be true and it will be included). You can change this behaviour
by specifying `filter_operator=AND`, so each filter must be true to be
included.
#### Filtering by Custom Field Values
For modules that include custom fields, you can search by the value of a
custom field by adding the `custom_field_` to the URL query
parameters. You **must** also specify the custom field in the `fields`
parameter.
```
GET
https://api.sonderplan.com/v2/booking?fields=id,name,custom_field_238938&custom_field_238938=Offline
```
This will return custom fields that contain the word 'Offline'.
contact:
email: info@sonderplan.com
version: '2.0'
servers:
- url: https://api.sonderplan.com
description: Production Server
security: []
tags:
- name: Booking
description: Booking related operations
- name: Project
description: Project related operations
- name: Resource
description: Resource related operations
- name: Contact
description: Contact related operations
- name: Quote
description: Quote related operations
- name: Invoice
description: Invoice related operations
- name: Invoice Template
description: Invoice template related operations
- name: Billable Item
description: Billable item related operations
- name: Rate Scheme
description: Rate scheme related operations
- name: Tax
description: Tax related operations
- name: Workspace
description: Workspace (formerly Schedule) related operations
- name: User
description: User related operations
- name: Group
description: Group related operations
- name: Status
description: Status related operations
- name: Custom Field
description: Custom field related operations
- name: Calendar Subscription
description: Calendar Subscription Import related operations
- name: Time Entry
description: Time Entry related operations
- name: Time Activity
description: Time Activity related operations
paths:
/v2/booking:
put:
tags:
- Booking
summary: Update Booking
description: >
`WRITE` access to the `SCHEDULE` module is required to access this
endpoint
The `bookingEdited` webhook will be fired when this endpoint has
run successfullyTo avoid generating lots of undesired
notifications, take care when creating or updating bookings and consider
using the `notify_user_resources` option which can be used to silence
notifications for end users.
operationId: cb4a41f148864769878d7abd3906f2b5
parameters:
- name: id
in: query
description: The ID of the booking to update
required: true
schema:
type: integer
format: int64
- name: check_clashes
in: query
description: >-
Report any clashes with new resources supplied, or existing
resources on the booking
schema:
type: boolean
- name: notify_user_resources
in: query
description: >-
Specifies if user resources (resources with a contact attached)
should be sent an email notification about the updated booking
schema:
type: boolean
default: true
- name: repeat_update_scope
in: query
description: >-
If updating a repeat booking, specifies if the changes should be
replicated to all, future or just the single booking. Default is
`single`
schema:
type: string
enum:
- single
- future
- all
requestBody:
description: Booking object that needs to be updated
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
$ref: '#/components/schemas/success'
'401':
description: Authorization information is missing or invalid
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/notFound'
security:
- bearer: []
components:
schemas:
Booking:
title: Booking Model
description: Standard booking model that returns most properties by default
type: object
allOf:
- properties:
id:
description: Booking ID
type: integer
example: 1
name:
description: Booking Name
type: string
example: Test Booking
start:
description: >-
Unix Timestamp of the booking start. Alternatively use
`start_date_time_iso` which automatically calculates the unix
timestamp.
type: integer
example: 1547501100
end:
description: >-
Unix timestamp of the booking end. Alternatively use
`end_date_time_iso` which automatically calculates the unix
timestamp.
type: integer
example: 1547538900
start_date_time_iso:
description: ISO-8601 formatted result of the booking start
type: string
example: '2022-02-22T09:00:00+11:00'
end_date_time_iso:
description: ISO-8601 formatted result of the booking end
type: string
example: '2022-02-22T17:00:00+11:00'
duration_min:
description: Duration of booking in minutes
type: integer
readOnly: true
example: '480'
all_day:
description: Is the booking all day
type: boolean
example: 'false'
notes:
description: Additional booking information
type: string
example: Additional note
repeat_master:
description: >-
Is this booking designated as the master booking linked to
repeats
type: boolean
example: 'true'
repeat_master_id:
description: >-
If this booking is a repeat, this is the id of the master
booking
type: integer
example: '0'
repeat_rule:
description: Specifically formatted rule for the repeat logic
type: string
example: FREQ=daily;INTERVAL=2;REPENDTYPE=date;UNTIL=20220228T130000;
resources:
type: array
items:
$ref: '#/components/schemas/ResourceBooking'
project:
type: array
items:
$ref: '#/components/schemas/ProjectSummary'
client:
description: >-
The client (either person or organization) attached to this
booking
type: array
items:
$ref: '#/components/schemas/Client'
status:
type: array
items:
$ref: '#/components/schemas/StatusSummary'
billable_items:
type: array
items:
$ref: '#/components/schemas/BookingBillableItem'
custom_fields:
type: array
items:
$ref: '#/components/schemas/CustomFieldOnObject'
type: object
- $ref: '#/components/schemas/extendedModelMeta'
success:
title: Success Response
properties:
success:
properties:
id:
type: integer
example: 1
type: object
type: object
notFound:
title: Not Found Response
description: Class OpenApi
properties:
error:
properties:
code:
description: The HTTP error code
type: integer
example: '404'
message:
description: More detail on the error encountered
type: string
example: Requested resource was not found
type: object
type: object
ResourceBooking:
title: Resource Booking Model
description: Resources added to a booking
properties:
id:
description: Automatically generated unique resource id
type: integer
example: 9458
name:
description: Name of the resource
type: string
readOnly: true
example: Edit Suite 1
description:
description: Additional info about the resource
type: string
readOnly: true
example: Sydney Office, Level 2
type_id:
description: 1 = Room, 2 = Person, 3 = Equipment, 4 = Resource Group, 5 = Action
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
readOnly: true
example: 1
type_person_id:
description: Unique id of the person (only applies if this resource is a person)
type: integer
readOnly: true
example: 0
updated:
description: The UNIX time value of the last update
type: integer
readOnly: true
example: 1388552400
parent_id:
description: The id of the resource group that is the parent of this resource
type: integer
readOnly: true
example: 99472
parent_name:
description: >-
The name of the resource group that is the parent of this resource.
Only appears when `resource_parent` is supplied as `true` as a query
parameter
type: string
readOnly: true
example: Edit Suites
icon:
description: >-
Only appears when `resource_icon` is supplied as `true` as a query
parameter
type: array
items:
$ref: '#/components/schemas/FileSummary'
readOnly: true
rates:
description: >-
Only appears when `resource_rates` is supplied as `true` as a query
parameter
type: array
items:
$ref: '#/components/schemas/BookingResourceRates'
time_entries:
description: >-
Only appears when `resource_time_entries` is supplied as `true` as a
query parameter
type: array
items:
$ref: '#/components/schemas/BookingResourceTimeEntry'
type: object
ProjectSummary:
title: Project Summary Model
description: Simplified project model containing only a subset of fields
properties:
id:
description: Automatically generated Project ID
type: integer
example: 2342354
name:
description: Title of the project
type: string
readOnly: true
example: Andor S1 EP7 Annoucement
code:
description: Short code used to identify the project
type: string
readOnly: true
example: AND-S1-EP7
description:
description: A short description or synopsis of the project
type: string
readOnly: true
example: >-
Colonel Yularen announces that the ISB has gained more surveillance
and punitive authority, while Meero is challenged by Blevin for
breaking protocol by accessing Imperial data without authorization.
start:
description: Unix Timestamp of the project start time frame.
type: integer
example: 1547501100
end:
description: Unix timestamp of the project end time frame.
type: integer
example: 1547538900
parent_id:
description: Project Parent ID
type: integer
readOnly: true
example: 9348
status_id:
description: Project Status ID
type: integer
readOnly: true
example: 1
type: object
Client:
title: Client model
description: Client model with some fields
properties:
id:
type: integer
readOnly: true
example: 4
uuid:
type: string
example: p4
name:
type: string
readOnly: true
example: Jane Someone
type:
type: string
enum:
- person
- organization
readOnly: true
example: person
email:
description: The primary email for this contact
type: string
readOnly: true
example: test@example.com
contact_person:
description: >-
Contact person at the client. This property is only valid if the
client is of type **organization**, and the contact must be a valid
client
properties:
id:
type: integer
example: 2837
name:
type: string
readOnly: true
example: Fred Flintstone
type: object
type: object
StatusSummary:
title: Status Summary Model
description: A simplified version of the complete Status Model
properties:
id:
description: Automatically generated unique identifier of the status
type: integer
readOnly: true
example: 2
name:
description: The name of the status
type: string
example: Second Hold
description:
description: Description of the status
type: string
example: Has second priority if the first hold cancels
notification:
description: Determines if notifications are sent if this status is selected
type: boolean
example: true
type: object
BookingBillableItem:
title: Billable Items on booking model
description: ''
required:
- name
properties:
id:
description: Automatically generated id
type: integer
example: 2342354
name:
description: Name of the billable item
type: string
example: NAS Storage
description:
description: Brief description of the item
type: string
example: Rented per TB, per month
cost:
description: Individual unit cost charged to the client
type: integer
format: float
example: '25.23'
buy_cost:
description: Individual unit cost payed by this business
type: integer
format: float
example: '20'
currency:
description: Currency code (three character format)
type: string
example: AUD
quantity:
description: Quantity of the item
type: integer
format: float
example: '4'
total:
description: Total, excluding taxes
type: integer
format: float
readOnly: true
example: '100.92'
buy_total:
description: Buy Total, excluding taxes
type: integer
format: float
readOnly: true
example: '80'
billable_item_id:
description: ID of the billable item (null if created adhoc)
type: integer
example: 897832
taxes:
type: array
items:
$ref: '#/components/schemas/InvoiceItemTaxes'
create_new:
description: Set to true to create a global billable item
type: boolean
example: true
type: object
CustomFieldOnObject:
title: Custom Field Module Value
description: Used to show the values of custom fields on linked modules
properties:
id:
description: The ID of the custom field
type: integer
example: 7823
name:
description: The name of the custom field
type: string
example: Type
value:
description: The text value of the custom field, null if not defined
type: string
example: Video Editing
value_id:
description: >-
The ID of the selected option, (applied only if the custom field is
of type `select`)
type: integer
example: 8973
update_key:
description: The update key to pass back when updating this field
type: string
example: '2_1_7823'
deprecated: true
type: object
extendedModelMeta:
title: Extended Meta Model
properties:
created_id:
description: The unique ID of the person (user) who created this record
type: integer
readOnly: true
example: 3
created:
description: The UNIX time value of the creation time
type: integer
readOnly: true
example: 1388552400
created_name:
description: The full name of the person (user) who created this record
type: string
readOnly: true
example: John Smith
updated_id:
description: The unique ID of the person (user) who last updated this record
type: integer
readOnly: true
example: 3
updated:
description: The UNIX time value of the last update
type: integer
readOnly: true
example: 1388552400
updated_name:
description: The full name of the person (user) who last updated this record
type: string
readOnly: true
example: John Smith
type: object
FileSummary:
title: File Summary Model
description: Simplified file model containing only a subset of fields
properties:
id:
description: Automatically generated File ID
type: integer
readOnly: true
example: 2342354
name:
description: Original file name
type: string
example: Avid_Icon
size:
description: File size (in bytes)
type: integer
example: 174285
alias:
description: Automatically generated file alias
type: string
example: 7e73ab25155974c230d09494548201b9f5056ef
extension:
description: File extension
type: string
example: png
mime_type:
description: File mime type
type: string
example: image/png
type: object
BookingResourceRates:
title: Booking Resource Rates Model
description: The rates associated with a resource for a booking
properties:
rate_scheme_id:
description: The ID (if applicable) of the rate scheme used to populate this rate
type: integer
example: 984312
rate_scheme_name:
description: The name of the rate scheme used to populate this rate
type: integer
example: Resource Rate
currency:
description: Currency code (three character format)
type: string
example: AUD
buy:
description: Contains the properties related to buy expenses
properties:
unit:
description: Unit of the buy outgoing
type: string
enum:
- hourly
- daily
- fixed
- auto
example: hourly
unit_amount:
description: Unit cost of the buy outgoing
type: number
format: float
example: '20.65'
quantity:
description: The quantity of the unit
type: number
format: float
example: '2.4'
discount:
description: >-
Discount amount that applies to this item. Suffix with a %
symbol to make this a percentage discount
type: string
example: 20.00%
type: object
sell:
description: Contains the properties related to sell expenses
properties:
unit:
description: Unit of the sell incoming
type: string
enum:
- hourly
- daily
- fixed
- auto
example: hourly
unit_amount:
description: Unit cost of the sell incoming
type: number
format: float
example: '20.65'
quantity:
description: The quantity of the unit
type: number
format: float
example: '2.4'
discount:
description: >-
Discount amount that applies to this item. Suffix with a %
symbol to make this a percentage discount
type: string
example: 20.00%
type: object
type: object
BookingResourceTimeEntry:
title: Booking Resource Time Entry Model
description: Time entries recorded by the owner against this booking resource
type: object
allOf:
- properties:
id:
description: Automatically generated, unique time entry id
type: integer
readOnly: true
example: 9879871
name:
description: Name of the activity that is being worked on
type: string
example: Colour Grading
description:
description: Short description or notes about what was worked on
type: string
example: Opening scenes completed
start:
description: Unix Time Entry Start
type: integer
example: 1547501100
end:
description: Unix Time Entry End
type: integer
example: 1547538900
type: object
InvoiceItemTaxes:
title: Invoice Item Taxes
description: Standard invoice item taxes model that returns tax information
properties:
id:
description: Unique id of the tax applied
type: integer
example: 3247
name:
description: Name of the tax
type: string
example: GST
rate:
description: Rate of the tax
type: string
example: '10.00'
total:
description: Total amount of tax
type: string
format: float
example: '151.00'
type: object
securitySchemes:
bearer:
type: http
scheme: bearer
````