The filter section allows you to retrieve a specified subset of the available data.
The filter section is a single JSON object with the following rules:
Equality
Use the following format to specify an equality condition:
Copy Code
{"query": {"filter":{"<field>":"<value>"}}}}
Operators
Use operators in the following format:
Copy Code
{"query": {"filter":{"<field>": {"<operator>":"<value>"},...}}}
For example, the following query will match all entities that have status
set to "CREATED"
or "UPDATED"
:
Copy Code
{"query": {"filter":{"status": {"$in": ["CREATED", "UPDATED"]}}}}
Each endpoint supports a subset of the following operators. See the specific endpoint's reference documentation for a list of supported operators.
- Comparison
$eq
- Matches values that are equal to a specified value.$ne
- Matches all values that are not equal to a specified value.$lt
- Matches values that are less than a specified value.$lte
- Matches values that are less than or equal to a specified value.$gt
- Matches values that are greater than a specified value.$gte
- Matches values that are greater than or equal to a specified value.$in
- Matches any of the values specified in an array.$hasSome
- Matches an array that contains at least one of the specified values.$hasAll
- Matches an array that contains all of the specified values.$startsWith
- Matches strings that start with a specified value. Case insensitive.$endsWith
- Matches strings that end with the specified value. Case insensitive.$contains
- Matches strings that contain the specified value. Case insensitive.
- Logical
$and
- Joins query clauses with a logical AND, and returns all documents that match the conditions of all clauses.$not
- Inverts the effect of a query expression and returns documents that do not match the query expression.$or
- Joins query clauses with a logical OR, and returns all documents that match the conditions of at least one of the clauses.
- Element
$exists
- Matches objects that have the specified field.
- Array
$hasSome
- Matches an array that contains at least one element specified in the query.$hasAll
- Matches arrays that contain all elements specified in the query
Sample Queries
The following example shows a compound query that returns all entities where status
is "NEW"
and either Quantity
is less than 30
or itemName
starts with the character P
:
Copy Code
{"query": {"filter":{"status": "NEW","$or": [{"Quantity": {"$lt": 30}}, {"itemName": {"$startsWith": "P"}}]}}}
The following example queries entities where the field tags value is an array with exactly two elements, "red" and "blank", in the specified order:
Copy Code
{"query": {"filter":{ "tags": ["red", "blank"] }}}
The following example queries for all entities where tags is an array that contains the string "red" as one of its elements, or that tags is the string "red":
Copy Code
{"query": {"filter":{"tags": "red" }}}
The following query matches entities that do not contain the item field, or where the item field has no value:
Copy Code
{"query": {"filter":{"item": {"$exists": false } }}}
The sort section is an array of field names and sort direction. If the direction is not specified, it will be sorted in ascending order:
Copy Code
{"query": {"sort": [{"fieldName":"sortField1"},{"fieldName":"sortField2","order":"DESC"}]}}
The paging section describes the size of the data set to return, and how many items to skip. For example, the following will return items 41-60. In other words, page number 3,with each page being 20 items:
Copy Code
{"query": {"paging": { "limit": 20, "offset": 40 }}}
The fields section is an array of field names and paths to return. Subsets of sub-objects can be returned by using dot notation. The following example returns firstName
from name
sub-object and the entire address
object
Copy Code
{"query": {"fields": ["name.firstName", "address"]}}
An API may provide named projections to save its clients from specifying the names of the fields in common use-cases.
For example, Contacts includes a fieldset named common
that contains only first name, last name, email, and phone number. If both fieldset and fields sections are specified, the returned items will include the fields specified in the fields
array and those defined in the fieldset.
Copy Code
{"query": {"fieldset": ["common"]}}
The response for a query request should be an object with the following structure:
Copy Code
{"result-object": [...], //Array of the result object"pagingMetadata": {"count": 33, // Number of items in the result-object array"offset": 3, // Offset of the first item in the result-object array"total": 36 // Total number of result-objects that match the specified filters.}}
When updating a resource, the Resources API uses PATCH endpoints and field masks. A PATCH endpoint means that only the fields specified in the request will be updated. Alternatively, a field mask explicitly lists the fields to update, regardless of which fields are specified in the request. You must use a field mask if you want to clear the value from a field.
The example below uses a field mask.
- The value of the
phone
field is updated - The value of the
email
field is cleared. - The
name
field is not updated as it is not included in the field mask.
Copy Code
{"resource": {"name": "John Smith","phone": "5553456"},"fieldMask": {"paths": ["phone","email"]}}
Deprecation Notice
This endpoint has been replaced with Query Resource and will be removed on March 31, 2022. If your app uses this endpoint, we recommend updating your code as soon as possible.
Retrieves a list of the resources according to the provided filters and paging. Resources that are in a resource group (i.e. the group_id property contains an ID) are excluded from the result for backwards compatibility.
This query is optional. If no query is provided than all non-deleted resources are returned.
Property | Is supported |
---|---|
filter | supports resource.id , resource.tag , resource.status |
paging | supported |
fields | supported |
fieldsets | not supported |
sort | not supported |
Permissions This endpoint requires the Read Bookings Calendar, Read Bookings - Public Data, Read Bookings - Including Participants or Manage Bookings permission scope.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Creates a resource.
Bookings resources are created with a schedule. The schedule and its sessions determine the resource's availability. Note that the schedule must contain a start date in the availability.start
property.
For resources that are available during the business's default hours, add the business's schedule as a linked schedule in the resource's schedule. For resources that have their own hours, create sessions with type "WORKING_HOURS"
using the resource's schedule.
You can use both individual and recurring sessions to define resource availability. You cannot use availability constraints for resource schedules.
Use the following steps to create resources:
- Create the resource using including schedule information.
- If the resource uses the default business hours, get the business resource's schedule ID and include it in the
scheduleInfo.availability.linkedSchedules
array in the in the schedule parameters. - If the resource has its own custom working hours, create sessions of type
"WORKING_HOURS"
. Use thescheduleId
of the new resource when creating the sessions. These session can be single sessions or recurring sessions. You can have both business hours and custom hours for the same resource schedule.
Notes:
- A resource can have one schedule only.
- You can have up to 135 active resources and an additional 135 deleted resources.
- The
businessLocation.businessSchedule
object in theschedule.location
object is not supported.
Permissions: This endpoint requires the Manage Bookings permission scope.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves a list of the resources according to the specified filters and paging.
The query parameter is optional. If no query is provided then all non-deleted resources are returned.
Resources that are in a resource group (i.e. the group_id property contains an ID) are excluded from the result for backwards compatibility unless the include_resources_with_groups
request field is set to true.
Property | Is supported |
---|---|
filter | supported fields: resource.id , resource.tags , resource.status |
paging | supported |
fields | supported |
fieldsets | not supported |
sort | not supported |
Notes:
- The following objects in the
query
parameter are not supported for this query:
sort
fieldsets
Permissions This endpoint requires the Read Bookings Calendar, Read Bookings - Public Data, Read Bookings - Including Participants or Manage Bookings permission scope.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Updates a resource.
Use this endpoint to update all resource information except for the resource's schedule. To update a resource's schedule use the Update Schedule endpoint.
Notes:
- When updating a resource you cannot change the system tags used by the Wix Bookings app. Tags used by the app have the values
"business"
and"staff"
.- When updating a resource's schedule you cannot change the resource tag used by the Wix Bookings app. Tags used by the app have the values
"INDIVIDUAL"
,"GROUP"
, and"COURSE”
.- The
businessLocation.businessSchedule
object in theschedule.location
object is not supported.
Permissions: This endpoint requires the Manage Bookings permission scope.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Updates a resource's schedule
To update a resource's schedule to remove business hours and add custom hours:
- Update the resource's schedule to remove the business's
scheduleId
from theavailability.linkedSchedules
array. - Create a set of recurring sessions of type
"WORKING_HOURS"
to define the resource's new hours.
To update a resource's schedule to add default business hours, and keep or remove custom hours:
- Update the resource's schedule to add the business resource's
scheduleId
to theavailability.linkedSchedules
array. - If you want to remove the custom sessions, delete the resource's sessions of type
"WORKING_HOURS"
. You do not have to delete exiting custom sessions. Custom session that are not deleted will continue to be included in availability calculations and can still be booked.
Notes:
- A resource can have one schedule only.
- A resource can have both default business hours and custom hours in its schedule.
- When updating a resource's schedule you cannot change the system tags used by the Wix Bookings app. Tags used by the app have the values
"INDIVIDUAL"
,"GROUP"
, and"COURSE”
.- The
businessLocation.businessSchedule
object in theschedule.location
object is not supported.
Permissions: This endpoint requires the Manage Bookings permission scope.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Deletes a resource.
Deleting a resource updates its status
to "DELETED"
.
You cannot delete a resource if it has booked sessions.
Notes:
- The Bookings app creates a resource with
"business"
in name and tag values. This resource is used for the business's schedule and working hours and cannot be deleted.- You can have up to 135 active resources and an additional 135 deleted resources.
Permissions: This endpoint requires the Manage Bookings permission scope.