ChiDesk API v2 reference

All six query parameters must appear in the URL by name, including the ones that look optional. Send them empty (stateId=&find=&clientId=) when you do not want to filter on them - omitting a name entirely means the request never reaches this action. Verified against a running server: you get a 405, not a 404, because POST /api/v2/appointments is registered on the same path, so the path still exists for another method once the GET is ruled out.

The range is capped at 90 days. A wider range returns 400 with the message "Maximum date range is 90 days".

Array parameters repeat the name once per value: services=<guid>&services=<guid>.

Every parameter below must be present by name. Send empty values for the ones you are not using.

Same query parameters as the GET form. This variant exists only because the cart has to travel in the request body, which a GET cannot carry.

The body is a bare JSON array of AppointmentService objects - not an object wrapping the array.

A cart that is no longer bookable still returns 200 - not a 4xx. Success is an empty response body; a failure is a 200 whose body is a comma-separated list of the items that went away, for example "Swedish Massage 60min is no longer available". Treat any non-empty body as a failure.

The body is a bare JSON array of AppointmentService objects.

Use this to drive a calendar picker, then call availabletimes for the day the client chooses.

siteId travels in the query string; the appointment itself is the JSON body.

Use an empty Guid (00000000-0000-0000-0000-000000000000) for the primary keys of anything you are creating.

Send AppointmentId in the body as well as in the route. The record that gets loaded and saved is the one named by the body's AppointmentId, while the response echoes the id from the route - so if the two disagree you will update one appointment and be told about another. Keep them identical.

This is one of the endpoints that takes its id in the route. Several others take it in the query string instead; see Conventions.

Both ids travel in the query string; there is no request body.

State ids come from the Appointment states category.

Only siteId is required. The other three carry defaults and may be left out of the URL altogether - unlike GET /api/v2/appointments, where every name has to be present.

find is a starts-with match, not a contains match, and it is tried against first name, last name, "first last", client code, e-mail, mobile number and membership number. Searching for "smith" finds Smith but not Smithers-Jones under a first name of Anne; searching for "ann" finds Anne.

creationDate reads as a single day but behaves as a from-date: clients created on or after that moment are returned. Use it to poll for new clients since your last sync.

itemState is not a wildcard - see Conventions. Ask for Active or Inactive; All returns nothing.

This route takes no siteId. The client is found by its id alone, so a client at any site on the account can be read here - a list restricted to one site does not restrict this.

The response body is the matching client's id on its own, or the literal null - not an object, and not a 404. Read it as a nullable Guid.

The comparison is case-insensitive and surrounding whitespace is trimmed. Only Active clients are considered, and only ones with an e-mail address recorded.

If two clients share an address you get the first one, with no indication that there was more than one.

The client is resolved by clientId AND email together - both must match the same Active client, and that client must have an e-mail address recorded. This verifies a password for a client you have already identified; it does not look a client up. Get the id from GET /api/v2/clients/emailexists first.

Success is 200 with an empty body. Failure is 401 with an empty body, and every kind of failure looks the same - wrong password, wrong e-mail for that id, unknown id, or an inactive client. That is deliberate; do not try to tell them apart.

This 401 is the one place in the API where 401 means something other than a credential problem. Your own bearer token is still fine - an authorization failure on this endpoint would have been a 403. Do not let a shared HTTP handler treat this 401 as "my token expired" and re-authenticate.

Leading and trailing whitespace is stripped from both the e-mail and the password before checking.

Passwords are held as PBKDF2 hashes. A client still on the older hash is migrated to PBKDF2 the first time they sign in successfully, so the first successful call for such a client also writes to their record.

The body is the client's id on its own, or the literal null.

The number is compared as text after trimming, so it has to be stored in the same format you send. There is no normalisation of country codes, spaces or leading zeros - +27821234567 does not match 0821234567.

Only Active clients with a mobile number recorded are considered.

This is not the client list with extra columns. Every client who has not agreed to receive marketing messages is excluded, always, whatever you pass - there is no parameter that turns that off. Use it as your marketing list and you inherit the account's consent record; use GET /api/v2/clients if you want every client.

The three channel filters are three-state. Leave one out to ignore that channel; send true for clients who accepted it; send false for clients who explicitly declined it. false is not the same as leaving it out.

find here is a contains match, not the starts-with match used by GET /api/v2/clients. The same term can return more rows here than there.

Ordered by last name.

The range is capped at 730 days - two years, not the 90 days most date-ranged endpoints allow. A wider range returns 400 with "Maximum date range is 730 days".

An appointment is returned only when it falls entirely inside the range: it must start at or after start and end at or before end. One that straddles either edge is left out, so widen the range slightly rather than aligning it exactly to a month boundary.

Scoped to the site as well as the client, so a client seen at two sites needs one call per site.

siteId travels in the query string; the client is the JSON body. Use an empty Guid for ClientId.

To give the client a portal password, send it in AccountPassword. ChiDesk hashes it and stores only the hash - the plain value is never written to the client record. Leave the field out and the client simply has no password.

On update the field is called NewAccountPassword instead. Sending AccountPassword to the PUT does not change the password.

Check for an existing client with GET /api/v2/clients/emailexists or /mobileexists first. Nothing here stops you creating a second record for the same person.

The id goes in the query string as clientId, not in the path - see Where the record id goes. There is no PUT /api/v2/clients/{id}.

The record that is loaded and saved is the one named by the query's clientId. The body's ClientId is not what selects it.

To change the password, send the new value in NewAccountPassword - not AccountPassword, which is the create-time field: a value sent there on a PUT is written to the record as sent and does not change the password. Leave NewAccountPassword out to keep the existing password.

Fetch the client first and send it back with your changes applied. Fields you send overwrite the stored ones.

The range is matched against when the form was captured, not against the date of any appointment it belongs to.

The end of the range is widened by one day before the query runs, so a form captured during the end date itself is included. Passing the same value for start and end returns that whole day rather than nothing.

There is no cap on the range here, and no filter beyond the dates - a wide range on a busy account returns a lot of data. Page it yourself by asking for shorter periods.

All three parameters are required by name: none of them carries a default.

Only siteId is required; itemState and find carry defaults and may be omitted.

This is every employee, not only the ones who can be booked. Whether a given employee can perform a given service is decided when you search for available times.

The range is capped at 90 days. A wider range returns 400 with "Maximum date range is 90 days".

A schedule is returned when it overlaps the range at all, not only when it sits inside it - so a shift that started before start and ends inside it is included, and its own Start is before the range you asked for. Clip the times yourself if you are drawing a calendar.

This returns both working time and time off. Read the schedule type on each row rather than assuming a row means the employee is available.

includeClasses carries a default and may be omitted. Leave it out and class time is not part of the roster.

One of only two endpoints in the API that are account-wide rather than site-scoped - it takes no siteId. The other is GET /api/v2/reports/sales.

state is genuinely optional here and may be omitted: it carries a default, so the request still resolves without it.

state is not a wildcard - see Conventions. Ask for Active or Inactive; All returns an empty list rather than every site.

The range is capped at 90 days. A wider range returns 400 with "Maximum date range is 90 days".

A record is returned when either its clock-in or its clock-out falls in the range, so a shift that ran over midnight at the edge of the range appears once, from the side that fell inside it.

The end of the range is widened by one day before the query runs, so records on the end date itself are included.

find is a contains match on the employee's first or last name.

find carries a default and may be omitted; siteId, start and end may not.

Records not tied to a single site are included whatever siteId you pass.

Ordered by clock-in time.

Only siteId is required. itemState, find and showPackageServices all carry defaults and may be left out.

Services that are components of a package - the individual treatments inside it, which are not sold on their own - are left out by default. Pass showPackageServices=true to see them as well.

A service with no site restriction on it belongs to the whole account and is returned for every siteId.

find is a contains match.

itemState is not a wildcard - see Conventions.

Read the allowSale note carefully - the default is not "no filter". Leaving it out returns only the products that are NOT flagged for sale, which for most accounts is a short and surprising list. If you want the sellable retail range, pass allowSale=true explicitly. There is no way to ask for both in one call; make two.

Only siteId is required. itemState, find and allowSale all carry defaults and may be left out.

A product with no site restriction on it belongs to the whole account and is returned for every siteId.

Cost and quantity are read per site, so the same product returns different figures at different sites.

itemState is not a wildcard - see Conventions.

All three parameters are required by name here, including find. This is the one catalogue endpoint that declares no defaults, so unlike Services, Products, Courses and Memberships you cannot call it with siteId alone - that returns 404, not the list. Send itemState and find even when you do not want to filter: ...&itemState=Active&find=.

A package with no site restriction on it belongs to the whole account and is returned for every siteId.

find is a contains match over name, code and barcode.

itemState is not a wildcard - see Conventions.

Only siteId is required; itemState and find carry defaults and may be omitted.

This lists the courses on the price list, not the courses a particular client has bought or how much of one is left.

A course with no site restriction on it belongs to the whole account and is returned for every siteId.

find is a contains match over name, code, category and barcode.

itemState is not a wildcard - see Conventions.

Both parameters are required by name; neither carries a default.

start is not a range and not a filter on when the class runs - it drops classes that had already finished by that moment. Pass the current time to get the classes still on offer, or an earlier date to include ones that have since ended.

Only Active classes are returned. There is no itemState here.

bookOnline defaults to true, and that default filters: leave it out and you only see schedules whose class is flagged as bookable online. Pass bookOnline=false to see the whole timetable including the internal-only sessions.

Only Active schedules are returned; cancelled and inactive ones are not, and there is no parameter to include them.

classType picks Class (1) or Event (2). The value All (0) is not a wildcard - it matches a class type of 0, which nothing has. Make one call per type if you need both.

siteId, classType, start and end are required by name. find, employeeId and bookOnline carry defaults and may be omitted.

There is no cap on the date range here.

siteId travels in the query string; the class is the JSON body. Use an empty Guid for ClassId.

This creates the definition, not a dated session of it.

The id goes in the query string as classId, not in the path - see Where the record id goes. There is no PUT /api/v2/classes/{id}.

The record loaded is the one named by the query's classId, but the site it is saved against comes from the body's SiteId. Always send SiteId in the body; leave it out and the class is saved against an empty site id, which is not recoverable through the API.

Fetch the class first and send it back with your changes applied.

All four parameters are required by name; none carries a default.

classType picks Class (1) or Event (2), and All (0) is not a wildcard here either.

There is no cap on the date range.

siteId travels in the query string; the booking is the JSON body.

ClassScheduleId in the body says which dated session the client is booking - it is read from the body, not the query string, and the whole schedule is loaded and re-saved around your booking.

The response Value is whatever ClassBookingId you sent, not a server-assigned id.

No siteId is needed: the site is looked up from the booking itself.

The response Value is the body's ClassBookingId, not the query parameter's.

ClassScheduleId in the body says which session the booking belongs to after the change, so moving a client to another session means changing it.

Only siteId is required; itemState and find carry defaults and may be omitted.

These are the plans on offer, not the clients who hold one. A client's own membership is on their Client record.

A plan with no site restriction on it belongs to the whole account and is returned for every siteId.

find is a contains match over name and code.

itemState is not a wildcard - see Conventions.

All five parameters are required by name, including find. Send it empty when you do not want to filter: ...&find=. Leaving a name out does not return the list - verified against a running server, it returns 405, because POST /api/v2/accountingdocuments shares this path and keeps it alive for another method once the GET is ruled out.

clientDocuments is a switch between two fixed sets, not a filter you can widen. true returns client invoices, credit notes and quotations. false returns debit notes, goods received notes, purchase orders, supplier invoices and stock transfers. There is no value that returns both, so a full picture is two calls.

Neither side returns the two recurring document types - recurring client invoices and recurring supplier invoices are absent from this list whatever you pass, with no error. If you reconcile invoices from this endpoint alone you will be short by exactly the recurring ones. Subscribe to the NewRecurringClientInvoice and NewRecurringSupplierInvoice WebHook events to catch them.

The end of the range is widened by one day before the query runs, so documents dated on the end date itself are included - and so are any dated in the first moments of the following day. Do not use this endpoint to build non-overlapping day buckets without allowing for that.

find is a starts-with match on the client or supplier name, or on the document number.

There is no cap on the date range here, unlike the appointment and roster endpoints.

Ordered by document date. Each row also carries a fiscal status where the account is fiscalised.

This route takes no siteId, and no clientDocuments switch - any document type can be fetched by its id, including the recurring ones the list will not show you.

The id must be a well-formed Guid. Anything else does not match the route and returns 404.

AccountingDocumentTypeId in the body decides what kind of document this is, and there is no default: 1 client invoice, 2 quotation, 3 credit note, 9 purchase order, 10 supplier invoice, 11 debit note, 12 goods received note, 13 stock transfer. Get it wrong and you get a valid document of the wrong type, not an error.

Send SiteId in the body as well as siteId in the query string, and make them the same site. The new document is set up from the body's SiteId and then saved against the query's - they are read from different places, so a mismatch is not something the API will tell you about.

Use an empty Guid for AccountingDocumentId. LinkedAccountingDocumentId ties a credit note back to the invoice it credits.

Creating a document does not record a payment against it. That is a separate accounting entry - see Receipts.

The document that is loaded is the one named in the route - unlike the appointments PUT, which loads the one named in the body.

The site it is saved against comes from the body's SiteId. Send it, and send the document's real site; leave it out and the document is saved against an empty site id.

Fetch the document first and send it back with your changes applied. Fields you send overwrite the stored ones.

A document that has already been posted or fiscalised should not be edited through here - correct it with a credit note instead.

A document that does not exist comes back as 400 with the body "Record does not exist." - not 404. A 404 from this path means the id was not a well-formed Guid.

This removes the document rather than reversing it. On a posted or fiscalised document that is not what your accountant wants - raise a credit note instead.

All five parameters are required by name, including find. Send it empty when you do not want to filter. Leaving a name out returns 405 - verified against a running server - because POST /api/v2/accountingentries shares this path and keeps it alive for another method once the GET is ruled out.

entryType matches exactly one type per call: Receipt (1), Payment (2), RecurringReceipt (10) or RecurringPayment (11). There is no "all" value, so a full day's cash movement is up to four calls. Both names and numbers are accepted.

Unlike the Sales list, the recurring types are reachable here - ask for them by name.

The end of the range is widened by one day before the query runs, so entries dated on the end date itself are included, along with any in the first moments of the following day.

There is no cap on the date range.

This route takes no siteId and no entryType - any entry can be fetched by its id.

The id must be a well-formed Guid, or the route does not match and you get 404.

AccountingEntryTypeId in the body decides what this entry is: 1 receipt, 2 payment, 10 recurring receipt, 11 recurring payment. There is no default.

Send SiteId in the body as well as siteId in the query string, and make them the same site - the entry is set up from the body's SiteId and then saved against the query's.

Use an empty Guid for AccountingEntryId.

To mark an invoice as paid, create the entry here and allocate it against the document; the document itself is not edited.

The entry that is loaded is the one named in the route.

The site it is saved against comes from the body's SiteId, so send it and send the right one.

Fetch the entry first and send it back with your changes applied.

An entry that does not exist comes back as 400 with the body "Record does not exist." - not 404.

Removing a receipt leaves the document it was allocated against unpaid again. Check what depends on the entry before you delete it.

Only siteId is required; itemState and find carry defaults and may be omitted.

find is a starts-with match over the voucher number, the recipient and the barcode. To look a voucher up from a barcode scan, send the scanned value as find.

Vouchers not tied to a single site are included whatever siteId you pass.

itemState is not a wildcard - see Conventions.

Takes no siteId - the voucher is found by its id alone.

The id must be a well-formed Guid, or the route does not match and you get 404.

VoucherNumber has to be unique. If it is already in use the call returns 400 with a model-state error on VoucherNumber reading "A voucher with this number already exists." - the message is in the account's language, so match on the field name rather than the text.

The uniqueness check runs against the body's SiteId, while the voucher is created at the query string's siteId. Send the same site in both, or you can be told a number is free at one site and have the voucher created at another.

A blank or missing VoucherNumber skips the uniqueness check altogether - it does not fail validation here.

Use an empty Guid for VoucherId. Send SiteId in the body.

The voucher that is loaded is the one named in the route.

SiteId in the body is mandatory in practice even though nothing says so: it is used to save the record and is read without a null check, so a body without it fails with a 500. Send the voucher's real site.

The uniqueness rule is not applied on update - changing VoucherNumber to one that already exists is not rejected here. Check it yourself with the list endpoint first.

Fetch the voucher first and send it back with your changes applied.

The range is capped at 365 days here, not the 90 days that appointments and rosters allow. A wider range returns 400 with "Maximum date range is 365 days".

siteId is genuinely optional and may be left out entirely. Leave it out and the report covers every Active site on the account - inactive sites are not included even though their history exists. Supply it and the report is scoped to that one site, active or not.

Employee names and voucher redemptions are always included; there is no parameter to turn them off.

This is the most expensive endpoint in the API. It reads a year of transactions across every site if you let it, and the rate limit still applies - ask for one wide range rather than looping over weeks.

The two body fields are snake_case - target_url and event - unlike the PascalCase fields everywhere else in the API. They are read straight off the raw JSON body.

Both fields are required, and neither is validated. If either is missing the request fails with a 500 rather than a 400 with a helpful message.

A URL may be registered once. Registering a target_url that already exists returns 409 Conflict and changes nothing - to point an existing hook at a different event, unregister it first.

ChiDesk records the client_id of the credential that registered the hook, so you can see which integration owns it.

This DELETE carries a request body, which is unusual - some HTTP clients will not send one on a DELETE without being told to. In .NET, build an HttpRequestMessage and set its Content rather than calling DeleteAsync.

The hook is identified by target_url, not by the id returned when it was created.

Unregistering a URL that was never registered still returns 200.

This endpoint is a development aid, not a substitute for registering a hook. It returns the latest records for the event rather than only ones you have not seen.

An event name that is not recognised returns 200 with an empty body rather than an error - so a typo looks like "no data". Check the name against the table below.

siteId and records are genuinely optional and may be omitted. When siteId is left out ChiDesk uses the account's main site.

siteId is the only parameter, and it is required by name.

Alerts not tied to a single site belong to the whole account and are returned for every siteId.

Ordered by category, then name - use the category to group them in your own UI.

Every row comes back with its selected flag false. That field is for the back-office editor; it does not tell you which alerts are set on a given client.

A ChiDesk account is one ClassPass partner, so this always returns a single partner and a pagination block that says page 1 of 1. page and page_size are accepted and have no effect on what comes back.

last_updated is generated at request time as "yesterday", not read from the record. Do not use it to detect changes.

This is the one path in the category that ends in a literal segment, so api/v2/classpass is the only usable endpoint allow-list line here.

The partner_id in the path is not checked against anything. Whatever you put there, you get the account resolved from the host name - so this returns the same record as the list above, wrapped in a partner_item instead of an array.

last_updated is generated at request time, not stored.

Only Active sites are published. An inactive site is not a venue.

venue_id is the ChiDesk siteId with its hyphens removed.

The country in the address is translated from the site's stored country name to a two-letter code where ChiDesk recognises the name. A country it does not recognise is passed through as the stored text, so handle both.

phone is always null on this endpoint.

last_updated is generated at request time, not read from the site.

venue_id is a ChiDesk siteId, with or without hyphens. A value that is not a Guid in either form fails with a 500 rather than a 404.

Unlike the list, this reads the site's full address record. The same country-code translation applies.

phone is always null.

Only Active services are published, and services that exist only inside a package are left out.

duration and late_cancel_window are XML Schema durations - PT1H for an hour, PT30M for thirty minutes - not minutes and not ISO timestamps.

start_interval is the site's booking time scale in minutes: the granularity that start times are offered on.

late_cancel_window comes from the site's cancellation-period setting, so it is the same for every service at the venue.

Paging works correctly on this endpoint - the pagination block matches what you asked for. That is not true of the venues endpoint.

An allow-list line of api/v2/services does NOT reach this path, and a bare line of services would match both this and the ordinary service list. Leave the allow-list empty for ClassPass credentials.

type is always PRACTITIONER. Booking a room or a piece of equipment rather than a person is not supported through this integration.

services on each bookable is the list of service ids that practitioner can perform, hyphens stripped. Cross-reference it with the services endpoint.

gender is reported as Man, Woman or "Not specified", which is the ClassPass vocabulary rather than ChiDesk's own.

Only employees who can take appointments are listed, so this is narrower than GET /api/v2/employees.

Paging works correctly on this endpoint.

start_date and end_date are required, and they are the venue's LOCAL dates, not UTC. The windows that come back are local times in ISO 8601 with no zone designator - so 2026-08-03T09:00:00 means nine in the morning at that venue.

end_date behaves as exclusive: the days walked are start_date up to but not including end_date, because the count is the whole-day difference between them. Ask for one day past the last day you want.

The result is cached for five minutes against the exact combination of partner, venue, start_date and end_date - which is what makes paging through a large range cheap, and also means a booking made in the last five minutes may still show as free. Change the range or wait it out if you need it fresh.

A practitioner with no free windows in the range is left out of the response entirely rather than returned with an empty array.

Windows are computed from shifts (or the site's trading hours, for full-time staff), minus existing appointments and time off, and closed days are skipped altogether.

The pagination block is correct here, but note that total_pages is computed before the page is sliced.

ChiDesk creates the client for you when it has never seen the member's e-mail address before, using the name, e-mail, phone, gender and country from the user object. If the address is already on file the existing client is reused, so repeat members do not accumulate duplicates.

The placeholder mobile number +10000000000 is treated as no number and stored blank.

appointment_id is the id ClassPass assigns. ChiDesk converts it into a Guid and uses it as the appointment's service id, which is what makes the later status and attendance calls work - so it has to be the same value you send back on those.

Only the first entry in bookables is used. Sending several does not book several practitioners.

start_datetime is the venue's local time and is converted to UTC on the way in.

Where the site has a source named CLASSPASS, the appointment and any client created here are attributed to it. If no such source exists the booking still succeeds, unattributed - so create one if you want ClassPass business to show up separately in reporting.

Errors on this endpoint come back as 500 with the underlying message in the body, including ones that are really bad input - an unparseable start_datetime returns 500 with "Could not parse start date: ...", not a 400. Read the message, but do not retry a 500 from here without changing the request.

The response echoes the ClassPass appointment_id you sent. It does not return the ChiDesk appointment id.

This is the only PATCH in the whole API. A client library that only speaks GET, POST, PUT and DELETE will not reach it.

Only two status values do anything: CANCELLED moves the appointment to the site's cancelled state, and LATE CANCELLED does the same but prefers an inactive state named "Late Cancelled" if the site has one. Both are matched exactly, in upper case.

Any other status value is accepted and changes nothing, and the response is still 200. There is no validation of the value and no way to tell from the response that it was ignored.

An appointment_id that does not resolve returns 404 with "Appointment not found: <id>" - one of very few genuine 404s in this API.

Send the same appointment_id you sent when creating the appointment. ChiDesk converts it back to find the record.

A request with no body fails with a 500, not a 400 - the status is read without a null check.

There is no "not found", no "no show" and no "pending" - the two values are the whole vocabulary.

cp_user_id always comes back empty.

appointment_id is echoed back exactly as you sent it.

last_updated is generated at request time, not read from the appointment.

siteId is the only parameter, and it is required by name.

State names are per account and can be renamed, so never match on the name. Read the ids once at start-up and cache them.

Every state is returned, whether or not it counts as live. The Active flag on each row is what tells you which is which: a state with Active true is one where the appointment is still going to happen, and false covers the closed-out ones such as cancellations and no-shows.

States not tied to a single site belong to the whole account and are returned for every siteId.

Ordered by the sort order set in the back office, which is the order the account expects to see them in.

The list is cached per account and refreshed when the states change, so it is cheap to call - but do not poll it to detect configuration changes.

siteId is the only parameter, and it is required by name.

Only Active sources are returned, and there is no parameter to change that - an inactive source cannot be listed here even though appointments may still reference it. If you meet a SourceId this endpoint does not explain, that is why.

Sources not tied to a single site belong to the whole account and are returned for every siteId.

Ordered by name.

The list is cached per account and refreshed when the sources change, so it is cheap to call.

Ask the account to add a source for your integration and tag what you create with it. That is what makes your bookings separable in their reporting - and it is how the ClassPass integration attributes its own.