The appointments, soonest start first
https://api.app2email.com/v1/{number}/bookings Scope: bookings:manage (or messages:read). Booked on WhatsApp, from the dashboard or through the API. Filter by a range of days (business time zone) or times, a status, or one contact; order=desc for the latest start first. Page with next_cursor.
Path
-
Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.
e.g.4976659348270
Query
- from string
Only appointments starting at or after this day (YYYY-MM-DD, business time zone) or ISO 8601 time.
e.g.2026-11-10 - to string
Only appointments starting on or before this day (YYYY-MM-DD, included) or before this ISO 8601 time.
e.g.2026-11-16 - status string
Only this status.
confirmedcancelledcompletedno_show - contact string
Only this customer (number with country code, or business-scoped user id).
e.g.61412345678 - provider_id string
Only this staff member's appointments (GET /bookings/staff).
e.g.maria -
true: confirmed appointments starting now or later, soonest first (status, from, to and order are then ignored).
- q string
Appointments whose customer name, reference or number contains this text.
e.g.smith -
asc: soonest start first (default). desc: latest start first.
ascdesc -
How many (1 to 200, default 50).
- cursor string
The next_cursor of the previous answer, unchanged. Leave out for the first page.
Responses
Fields
- success boolean
- request_id string
- bookings object[]
30 item fields
- id integere.g.
42 - reference string
The short code the customer sees. GET /bookings/{id} takes it too.
e.g.BK-7Q3M2A - status string
confirmedcancelledcompletedno_show - contact string
The customer's number (digits, country code first) or their business-scoped user id.
e.g.61412345678 - contact_name stringe.g.
John Smith - contact_email stringe.g.
john@example.com - service object
3 fields
- id stringe.g.
haircut - name stringe.g.
Haircut - duration_min integere.g.
30
- start string (date-time)
UTC.
- end string (date-time)
UTC.
- timezone string
The business time zone the slot was chosen in.
e.g.Australia/Sydney - source string
Booked by the customer in WhatsApp, on the dashboard (or in the calendar app), through this API, or by the customer on the online booking page (web).
whatsapp_flowdashboardapiweb - calendar object
-
Every other field the customer filled in the Flow.
- notes string
- provider object
The staff member, when the business has them. Left out otherwise.
- rating integer
The customer's rating from the follow-up message (5 loved it, 3 OK, 1 not great). Left out until given.
135 - payment_status string
The business's own note on the payment. Left out when none.
link_sentpaidwaived - credits_used integer
Always 0 (memberships were removed on 2026-11-10); kept so existing integrations keep parsing.
- attendance_confirmed string (date-time)
When the customer tapped Confirm on a reminder.
- cancelled object
Only when cancelled.
- rescheduled_from_id integer
The appointment this one replaced.
- link_id integer | null
The online booking link (/book/...) it was made through, for correlation. null: none.
- notes_count integer
How many internal notes are written on this appointment (GET /bookings/{id}/notes). Given by the calendar routes and the list; left out of webhook events.
- created string (date-time)
- location object | null
Where it takes place, as chosen (null: the service has no locations; then config.messages.location). value: the address, the number, the link; a video link made by the connected Google or Microsoft calendar appears here once made. text: how the messages show it.
- addons object[]
The add-ons booked (copied at booking time).
4 item fields
- id string
- name string
- price_amount number
- duration_min integer
- guests object[]
The people who come along.
- answer_items object[]
The answers to the service's questions as label / value (the raw ones are in answers.q).
- series object | null
This appointment is one of a series (null: not).
- seats integer
The places this booking takes on a group time (1 + guests); 1 otherwise.
- next_cursor string
Pass it as cursor for the next page. Left out on the last page.
- count integer
- order string
ascdesc - enabled boolean
Whether Book-and-Pay is switched on for the number.
- timezone string
Errors
- 400 The request is malformed (missing or invalid fields, query parameters or times).
- 401 Missing, invalid, revoked or expired API key.
- 403 The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account.
- 404 The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found.
- 429 A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait.
- 500 Unexpected error on app2email's side.