Fetch a range of "events".
Please note that you can also use this API to fetch one event by id or external_id (for legacy reasons). The new proper way to fetch one event is to use the /v1/event (singular) API.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
If you do not specify a phone_number, email_address or participant_id... then events will not be duplicated, an each event will contain all of it's participants.
However, if you specify a phone_number, email_address or participant_id... then events may be listed more than once, and each event entry returned will only have the matching participant in the participants array included.
Searching
Pass a q query parameter to restrict the results to events that match a query expressed in Apptoto's appointment search language. Examples:
q=fred-- bare term, matches the event's title, location or content, or a participant's name, email or phoneq=fred smith-- multiple bare terms are ANDed; both must matchq="fred smith"-- quoted, matches the phrase exactlyq="Fred Smith" or "Jane Doe" or "Sam Brown"-- one request covering a list of people, instead of one request per personq=name:fred-- match against the participant name onlyq=event.title:haircut-- match against the event title onlyq=event.title="Haircut with Fred"-- exact title matchq=(fred or smith) -cancelled-- boolean combination with a negated termq=event.custom.service_type:haircut-- match a custom event field
begin / end, calendar_id and pagination (page, page_size) are applied on top of q.
If part of the query cannot be resolved -- most often an unrecognized field name -- the response includes a warnings array explaining why, and those clauses match nothing. A query that cannot be parsed at all (for example an unbalanced quote) returns a 400.
See the Appointment Search Syntax article for the full operator and field reference.
Result
Pass include_total=true to add a total to the response: the number of events matching the request across all pages, not the number in events. Use it to decide whether to request another page. It is off by default because computing it costs an extra count over the whole matched range -- on a wide date range or a large page_size that is not free.
Example Result (with include_total=true):
{
total: 1,
events: [ {
id: 123,
calendar_id: 456,
start_time: "2016-04-15T12:00:00-07:00",
end_time: "2016-04-15T13:00:00-07:00",
title: "Appointment with Fred",
location: "",
content: "",
is_deleted: false,
participants: [ {
id: 789,
name: "Fred Smith",
phone: "650-555-1212",
normalized_phone: "+16505551212",
email: "[email protected]",
state: "initial",
}],
custom_data: {
field_1: "custom value"
}
}]
}OAuth scope
Calls authenticated with an OAuth 2.0 bearer token must include the events:read scope. A token without it receives a 403 insufficient_scope response. HTTP Basic auth is not scope-gated.