Agendize Developers API

Home > Agendize Scheduling

Appointments

{ "id": {string}, "reference": {string}, "company": { "id": {string}, "name": {string} }, "service": { "id": {string}, "name": {string}, "externalId": {string} }, "resource": { "id": {string}, "name": {string}, "externalId": {string} }, "staff": { "id": {string}, "firstName": {string}, "lastName": {string}, "externalId": {string} }, "client": { "id": {string}, "firstName": {string}, "lastName": {string}, "email": {string}, "phone": {string}, "mobilePhone": {string}, "externalId": {string}, "timeZone": {string} }, "parent": { "id": {string}, "firstName": {string}, "lastName": {string}, "email": {string}, "externalId": {string}, "timeZone": {string} }, "start": { "dateTime": {datetime}, "timeZone": {string} }, "end": { "dateTime": {datetime}, "timeZone": {string} }, "created": { "dateTime": {datetime}, "timeZone": {string} }, "form": [ {FormItem object} ], "status": {string}, "customStatus": { "id": {string}, "name": {string} }, "notes": {string}, "history": [ { "text": {string}, "date": { "dateTime": {datetime}, "timeZone": {string} }, "source": {string}, "user": { "firstName": {string}, "lastName": {string), "email": {string}, "userName": {string} }, "type": {string} } ], "service-resource": [ { "id": {string}, "name": {string} } ], "meta-event": {boolean}, "type": {string}, "paid": {boolean}, "addToWaitingList": {boolean}, "source": {string}, "iterationCount": {integer}, "sendto": {string}, "synchronization": { "googleCalendar": { "id": {string} }, "office365Calendar": { "id": {string} }, "windowsLiveCalendar": { "id": {string} }, "salesforce": { "id": {string} } }, "rescheduleLink": {string}, "onlineMeeting": { "provider": {string}, "videoLink: {string} }, "encryptedId": {string}, "price": { "amount": {float}, "currency": {string} }, "location": {string}, "locationCustom": {string}, "extendedProperties": { "private": {object}, "public": {object} } }
Notes
id string Identifier of the appointment. Read only.
reference string Reference code of the appointment.
company object company details.
company.id string Identifier of the company.
company.name string Name of the company.
service object Service details. Only if the appointment is for a service.
service.id string Identifier of the service. writable. Max length 16.
service.name string Name of the service.
service.externalId string Unique service identifier from another (external) system. writable only.
resource object Resource details. Only if the appointment is for a resource.
resource.id string Identifier of the resource. writable. Max length 16.
resource.name string Name of the resource.
resource.externalId string Unique resource identifier from another (external) system. writable only.
staff object Staff details.
staff.id string Identifier of the company's staff member. writable. Max length 16.
staff.firstName string First name of the company's staff member.
staff.lastName string Last name of the company's staff member.
staff.externalId string Unique staff member identifier from another (external) system. writable only.
client object Client details.
client.id string Identifier of the client. the id is unique and should not be reused for another account. writable. Max length 16.
client.firstName string First name of the client. writable. Max length 127.
client.lastName string Last name of the client. writable. Max length 127.
client.email string Email Address of the client. writable. Max length 127.
client.timeZone string Time zone of the client. Only if time zone has been specified. writable
client.externalId string Unique client identifier from another (external) system. writable. Max length 65535.
client.phone string Phone number of the client.
client.mobilePhone string Mobile phone number of the client.
parent object For an appointment for someone else, details of the client who take the appointment.
parent.id string Identifier of the parent. the id is unique and should not be reused for another account. writable. Max length 16.
parent.firstName string First name of the parent. writable. Max length 127.
parent.lastName string Last name of the parent. writable. Max length 127.
parent.email string Email Address of the parent. writable. Max length 127.
parent.externalId string Unique parent identifier from another (external) system. writable. Max length 65535.
parent.timeZone string Time zone of the parent. Only if time zone has been specified. writable
start object The start time of the event. writable
start.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information). writable
start.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company. writable
end object The end time of the event. writable
end.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information). writable
end.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company. writable
created object Creation time of the event. Read-only.
form object The filled form of the event, see description below writable
status string The native status of the event. Values: "completed", "noShow", "accepted", "pending", "declined", "cancelled", "inProgress". writable
customStatus object The custom status of the event. Managed with the appointment statuses api. "status" and "customStatus" cannot be used in the same time. writable
customStatus.id string The identifier of the custom status. writable
customStatus.name string The name of the custom status. read-only
notes string Notes of the appointment. writable. Max length 65535.
history list Historic of updates on an appointment
history[] object History entry
history[].text string Status of the appointment
history[].date object Date of the appointment
history[].date.dateTime datetime Date of the appointment relative to the company time
history[].date.timeZone string Timezone related to the appointment date
history[].source string In the case of external cancellation, the source contains the cancellation's origin
history[].type string Type of change. Values: :
  • "booked"
  • "pending"
  • "accepted"
  • "finished"
  • "no_show"
  • "user_deleted"
  • "archived"
  • "in_progress"
  • "completed"
  • "declined"
  • "client_deleted"
  • "payment"
  • "changed_end"
  • "changed_service"
  • "started"
  • "user_rescheduled"
  • "user_rescheduled_changed_start"
  • "user_rescheduled_changed_staff"
  • "user_rescheduled_changed_resource"
  • "user_rescheduled_changed_client"
  • "user_rescheduled_changed_note"
  • "user_rescheduled_changed_field"
  • "client_rescheduled"
  • "client_rescheduled_changed_start"
  • "client_rescheduled_changed_staff"
  • "client_rescheduled_changed_resource"
  • "client_rescheduled_changed_client"
  • "client_rescheduled_changed_note"
  • "client_rescheduled_changed_field"
history[].user object Client concerned by the appointment
history[].user.firstName string Client's firstname
history[].user.lastName string Client's lastname
history[].user.email string Client's email
history[].user.userName string Client's login
type string The type of the event. Values: "normal" (appointment with a client) or "personal" (personal appointment). writable
paid string "true" if the appointment has been paid. writable
addToWaitingList string If "true", add the client to the waiting list. writable
iterationCount string Only for resource mode. Number of iterations. For insert/update only. writable
sendto string In case of an appointment for someone else, set if emails and text messages have to be sent to parent or client. Values: "parent", "client".
service-resource list List of service-resource details. Only if the appointment is for a service-resource.
service-resource.id string Id of the service-resource
service-resource.name string Name of the service-resource
meta-event boolean "true" if the appointment is meta event.
synchronization object Calendar and CRM synchronization data if the appoiment has been synchronized with each service.
googleCalendar object Google Calendar informations.
googleCalendar.id string Id of the event in Google Calendar.
office365Calendar object Office 365 Calendar informations.
office365Calendar.id string Id of the event in Office 365 Calendar.
windowsLiveCalendar object Windows Live Calendar informations.
windowsLiveCalendar.id string Id of the event in Windows Live Calendar.
salesforce object Salesforce informations.
salesforce.id string Id of the event in Salesforce.
rescheduleLink object Link to the reschedule page. Only if the appointment end is in futur. A finished appointment can't be rescheduled.
source string Source of the appointment. Free text.
onlineMeeting object Video conference link and provider.
onlineMeeting.provider string Provider of the video conference. Values: "agendize", "teams".
onlineMeeting.videoLink string Web link to the video conference.
encryptedId string Encrypted identifier of the appointment. Read only.
price object Price informations of the appointments. Only if the service has a price. Read-only.
price.amount float Price amount of the event.
price.currency string Currency of the company. Values: "USD", "CAD", "EUR", "GBP", "DKK", "JPY", "INR", "CNY", "MXN", "CHF", "NZD"
location string Localization of the appointment. Values: "companyAddress", "videoconference", "phone", "custom". Default: "companyAddress". writable
locationCustom string Custom localization of the appointment. Read only
extendedProperties object Extended Properties. You can defined your custom properties. Size limit: 22KB.
extendedProperties.private object Private properties. These properties are not retrieve in widget.
extendedProperties.public object Private properties. These properties are retrieve in widget.

Additional representation : FormItem

{ "id": {string}, "type": {string}, "title": {string}, "bind": {string), "bindGroup": {string}, "externalId": {string} "help": {string}, "placeholder" : {string}, "mandatory": {boolean}, "visible" : {boolean}, "otherValue": {boolean}, "category": {boolean}, "multiple": {boolean}, "fileName": {string}, "value": {string}, "values": [ { "id": {string), "name": {string}, "value": {string} "values": [ { "id": {string}, "name": {string}, "value": {string} } ] } ], "valueFormat": { "maxLength": {number}, "minLength": {number}, "regexType: {string}, "regexValue: {string}, "valueFormat": {string} }, "zonedDateTime": { "dateTime": {string}, "timeZone": {string} }, "subItem": [ {FormItem object} ] }
Parameter name Value Description Notes
FormItem.id string Id of the field. Can not be empty.
FormItem.type string Type of the field. Values:
  • "input": input text
  • "select": dropdown
  • "checkbox": check box
  • "radio": radio button list
  • "textarea": textaera
  • "title": text label
  • "file": file upload
  • "address": client full address
  • "date": date
  • "rating": rating range from 1 to 5
  • "number": number field
  • "pricing": number field with currency
FormItem.title string Title of the field.
FormItem.bind string Binding string form special fields. Values:
  • crm-name
  • crm-address
  • crm-address-firstline
  • crm-address-secondline
  • crm-address-city
  • crm-address-postalcode
  • crm-address-state
  • crm-address-country
  • crm-job-title
  • crm-company
  • crm-notifications
  • crm-language
  • crm-reference
  • crm-reminder
  • crm-birthdate
  • crm-miscellaneous-* : CRM additional fields (from 1 to 10)
Some other values are available but can only be set in the contactFields field :
  • crm-first-name
  • crm-last-name
  • crm-email
  • crm-phone
FormItem.bindGroup string Binding group string form special group of fields. Values:
  • crm
FormItem.externalId string External identifier of this field. When this value is set up, this field would be fulfilled by HTTP query parameters on the appointment> widget.
FormItem.help string Help text of the field.
FormItem.placeholder string Placeholder of the field.
FormItem.mandatory boolean If the field is mandatory.
FormItem.visible boolean If the field is visible by client.
FormItem.otherValue boolean Activate or deactivate the possibility to add a custom value to the field. Available for type radio, checkbox and select.
FormItem.category boolean Activate or deactivate the possibility to group values by category. Available only for type select.
FormItem.multiple boolean Activate or deactivate the possibility to select several values. Available only for type select.
FormItem.fileName string (Optional) When the value is a file, a fileName can be specified. If not specified, the file will be named "file" and get the extension from the media type
FormItem.value string Value of the field. For multi values fields (radio, checkbox and select), use "values" instead. With file type : get and list methods will return the link to the file, for insert and update methods it is the data URI scheme binary content of the file.
FormItem.values list Values list of the field. Available for type radio, checkbox and select.
FormItem.values[].id string Identifier of the field value.
FormItem.values[].name string Name of the field value.
FormItem.values[].value string Value of the field value.
FormItem.values[].values list List of values of the form field value. Available only for type select with option category set to True
FormItem.values[].values[].id string Identifier of the form field value. Available only for type select with option category set to True
FormItem.values[].values[].name string Name of the form field value. Available only for type select with option category set to True
FormItem.values[].values[].value string Value of the form field value. Available only for type select with option category set to True
FormItem.valueFormat object Input rules.
FormItem.valueFormat.maxLength number Value maximum length.
FormItem.valueFormat.minLength number Value minimum length.
FormItem.valueFormat.regexType string Type of regex.
FormItem.valueFormat.regexValue string Value of regex.
FormItem.valueFormat.valueFormat string Type or format
  • alphanumeric
  • numeric
  • regex
  • none
FormItem.zonedDateTime object If the field is a date type, the value is formatted and returned with his timezone Read only
FormItem.zonedDateTime.dateTime object The value of the field formatted. For example '2011-12-03T10:15:30' Read only
FormItem.zonedDateTime.timeZone object The date timezone. For example 'Europe/Paris' Read only
FormItem.subItem list List of sub FormItem, available for crm-address field and crm-name field.

Delete

Deletes an entry on the company's appointment list.

Authentication is required to execute this request. Please refer to Authentication for more.

Request

HTTP Request

DELETE https://api.agendize.com/api/2.1/scheduling/companies/{companyId}/appointments/{appointmentId}

Parameters

Parameter name Value Description
Path parameters
companyId string Company identifier.
appointmentId string Appointment identifier.
Optional query parameters
silent boolean If true, Email and SMS appointment notifications and reminder are not sent.

Request body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

Get

Returns an entry of the company's appointment list.

Authentication is required to execute this request. Please refer to Authentication for more.

Request

HTTP Request

GET https://api.agendize.com/api/2.1/scheduling/companies/{companyId}/appointments/{appointmentId}

Parameters

Parameter name Value Description
Path parameters
companyId string Company identifier.
appointmentId string Appointment identifier or appointment reference.
Optional query parameters
lang string Language use to retreive appointment history strings.
fields string Specify the fields returned. Comma separated field names (ex: "id,client").
levelDetail string Level of details returned in appointment properties. Optional. Values: "light" and "full". The default is "full".

Request body

Do not supply a request body with this method.

Response

If successful, this method returns an Appointment resource in the response body.

List

Returns entries on the company's appointment list.

Authentication is required to execute this request. Please refer to Authentication for more.

Request

HTTP Request

GET https://api.agendize.com/api/2.1/scheduling/companies/{companyId}/appointments

Parameters

Parameter name Value Description
Path parameters
companyId string Company identifier.
Optional query parameters
startDate datetime Upper bound (exclusive) for an appointment's start time (as a RFC 3339 timestamp) in GMT to filter by. Optional. The default value is now -1 month.
endDate datetime Lower bound (exclusive) for an appointment's end time (as a RFC 3339 timestamp) in GMT to filter by. Optional. The default value is now +1 month.
createdStartDate datetime Upper bound (exclusive) for an appointment's creation time (as a RFC 3339 timestamp) in GMT to filter by. Optional. The default is not to filter by creation time.
createdEndDate datetime Lower bound (exclusive) for an appointment's creation time (as a RFC 3339 timestamp) in GMT to filter by. Optional. The default is not to filter by creation time.
status string Status of appointments

Acceptable values are:

- "noShow"
- "accepted"
- "completed"
- "cancelled"
- "pending"
clientId string Client identifier.
serviceId string Service identifier. internal or external identifier.
staffId string Staff member identifier. internal or external identifier.
resourceId string Resource identifier. internal or external identifier.
q string Free text search terms to find appointments that match these terms in form fields.
externalClientId string Unique client identifier from another (external) system.
syncToken string Token obtained from the nextSyncToken field returned on the last page of results from the previous list request.
fields string Specify the fields returned. Comma separated field names (ex: "id,client").
personalAppointments string Include personal appointments.
showDeleted boolean Whether to include deleted appointment list entries in the result. Optional. The default is false.
levelDetail string Level of details returned in appointment properties. Optional. Values: "light" and "full". The default is "light".

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a list of Appointment resource in the response body.

{ items: [Appointment Resource] }

Insert

Adds an entry to the company's appointment list.

Authentication is required to execute this request. Please refer to Authentication for more.

Request

HTTP Request

POST https://api.agendize.com/api/2.1/scheduling/companies/{companyId}/appointments

Parameters

Parameter name Value Description
Path parameters
companyId string Company identifier.
Optional query parameters
lang string Language use to retreive appointment history strings.
force string Add the appointment without working time control. To force, the staff id need to be setted.
personalAppointmentSync string For personal appointment, use calendar sync or not. Value: "true" or "false".
silent boolean If true, Email and SMS appointment notifications and reminder are not sent.

Request body

In the request body, supply a Appointment Resource with the following properties:

Parameter name Value Description
Required Properties
client object Client details.
client.id string Identifier of the client.
client.firstName string First name of the client.
client.lastName string Last name of the client.
client.email string Email Address of the client.
service object Service informations. Only if the appointment is for a service.
service.id string Service identifier. You can also use service.externalId.
resource object Resource informations. Only if the appointment is for a resource.
resource.id string Resource identifier. You can also use resource.externalId.
resourceCount object Number of resources to book.
start object The start time of the event.
start.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information).
start.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company.
Optional Properties
end object The end time of the event.
! This property is only required and use for personal appointment.
end.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information).
end.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company.
staff object Staff informations.
! This property is only required for personal appointment.
staff.id string Staff identifier.
! This property is only required for personal appointment.
status string The status of the event. Values: "completed", "noShow", "accepted", "pending", "declined", "cancelled", "inProgress".
customStatus object The custom status of the event. Managed with the appointment statuses api. "status" and "customStatus" cannot be used in the same time. writable
customStatus.id string The identifier of the custom status. writable
customStatus.name string The name of the custom status. read-only
notes string Notes of the appointment. writable. Max length 65535.
client.externalId string Unique client identifier from another (external) system.
location string Localization of the appointment. Values: "companyAddress", "videoconference", "phone", "custom". Default: "companyAddress". writable

Response

If successful, this method returns a Appointment resource in the response body.

Update

Updates an entry on the company's appointment list.

Authentication is required to execute this request. Please refer to Authentication for more.

HTTP Request

PUT https://api.agendize.com/api/2.1/scheduling/companies/{companyId}/appointments/{appointmentId}

Parameters

Parameter name Value Description
Path parameters
companyId string Company identifier.
appointmentId string Appointment identifier or appointment reference.
Optional query parameters
calculateGeolocation boolean Calculate GPS coordonates from company's address.
Path parameters
companyId string Company identifier.
appointmentId string Appointment identifier.
Optional query parameters
lang string Language use to retreive appointment history strings.
force string Update the appointment without working time control. To force, the staff id need to be setted.
personalAppointmentSync string For personal appointment, use calendar sync or not. Value: "true" or "false".
silent boolean If true, Email and SMS appointment notifications and reminder are not sent.

Request body

In the request body, supply an Appointments resource with the following properties:

Parameter name Value Description
Optional Properties
client object Client details.
client.id string Identifier of the client.
client.firstName string First name of the client.
client.lastName string Last name of the client.
client.email string Email Address of the client.
service object Service informations. Only if the appointment is for a service.
service.id string Service identifier. You can also use service.externalId.
resource object Resource informations. Only if the appointment is for a resource.
resource.id string Resource identifier. You can also use resource.externalId.
resourceCount object Number of resources to book.
start object The start time of the event.
start.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information).
start.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company.
end object The end time of the event.
! This property is only required and use for personal appointment.
end.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information).
end.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company.
staff object Staff informations.
! This property is only required for personal appointment.
staff.id string Staff identifier.
! This property is only required for personal appointment.
status string The status of the event. Values: "completed", "noShow", "accepted", "pending", "declined", "cancelled", "inProgress".
customStatus object The custom status of the event. Managed with the appointment statuses api. "status" and "customStatus" cannot be used in the same time. writable
customStatus.id string The identifier of the custom status. writable
customStatus.name string The name of the custom status. read-only
notes string Notes of the appointment. writable. Max length 65535.
client.externalId string Unique client identifier from another (external) system.
location string Localization of the appointment. Values: "companyAddress", "videoconference", "phone", "custom". Default: "companyAddress". writable

Response

If successful, this method returns an Appointments resource in the response body.

Watch

Watch for changes to Appointment resources.

Authentication is required to execute this request. Please refer to Authentication for more.

The watch send an Appointment resource in the request body

Request

HTTP Request

POST https://api.agendize.com/api/2.1/scheduling/companies/{companyId}/appointments/watch

Parameters

Parameter name Value Description
Path parameters
companyId string Company identifier.

Request body

{ "address": {string}, "name": {string}, "basicAuth": { "username": {string}, "password": {string} }, "httpRequestHeader": { {name}: {string} }, "schema": {object}, "levelDetails": {string}, "method": {string}, "status": {string}, "oauth2Auth": { "grantType": {string}, "clientId": {string}, "clientSecret": {string}, "refreshToken": {string}, "authUrl": {string}, "accessTokenUrl": {string}, "redirectUri": {string} }, "signature": { "enabled": {boolean}, "cryptoKeyIds": [ {string} ] } }
Required Properties
address string The address where notifications are delivered for this watch.
Optional Properties
name string Name of the watch.
basicAuth string Credentials parameters for HTTP Basic authentication on the destination watch address. Only if you use this authentication method.
basicAuth.username string Username.
basicAuth.password string Password.
httpRequestHeader string Custom header parameters to send with the http request on the destination watch address.
httpRequestHeader.name string header parameter name.
schema object Custom json schema to apply for resource properties.
levelDetails string level json details for the resource. Values: "full" or "extraFull". Default value is "full".
method string HTTP Method to use for sending content. DELETE Method doesn't accept body content.
status string Status of the watcher. Values: "enabled", "disabled"
oauth2Auth string Credentials parameters for HTTP OAuth2 authentication on the destination watch address. Only if you use this authentication method.
oauth2Auth.grantType string OAuth2 grant type. Values: "refresh_token" (default), "client_credentials".
oauth2Auth.clientId string OAuth2 client id.
oauth2Auth.refreshToken string OAuth2 refresh token. Only for grantType "refresh_token"
oauth2Auth.authUrl string OAuth2 interactive end point to initiate the generation of the refresh token. Only for grantType "refresh_token"
oauth2Auth.accessTokenUrl string OAuth2 end point to generation an access token from the refresh token.
oauth2Auth.scope string OAuth2 api scope. Only for grantType "refresh_token"
signature object Produces a crypto signature of the watched content.
signature.enabled boolean Sets if the signature is enabled or not.
signature.cryptoKeyIds list Arrays of string of crypto keys identifier.

Response

If successful, this method returns a watch resource in the response body.

Examples of schema:

With JSON, only for string value:

{ "schema": { "my_id_key": "{id}", "dataContent": { "givenName": "{firstName}" } } }

With string to support typed values:

{ "schema": "\"my_id_key\": ${$.id}, \"dataContent\": { \"fullName\": \"${$.firstName} ${$.lastName}\"}" }

Replacement string can by defined with jsonpath expressions.

Watch event supported

  • Appointment added in dashboard. In this case, the watch request add the following header property in http request:
    X-Agendize-objectEvent: created
  • Appointment modified in dashboard. Appointment status changed: in progess, payed, no show, completed, accepted, declined. In this case, the watch request add the following header property in http request:
    X-Agendize-objectEvent: updated
  • Appointment cancelled in dashboard or widget In this case, the watch request add the following header property in http request:
    X-Agendize-objectEvent: deleted
  • At the start and end time of the appointment, transient field is added : "event". Value can be "started" or "finished"

When a watch is sent an additional json properties is added:

{ "date": { "dateTime": "{string}", "timeZone": "{string}" }, "event": {string} }
Parameter name Value Description
date object The date of the watcher sent.
date.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information).
date.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company.
event string Event on the object. Values: "created", "updated", "deleted".

Agendize | Support | Status

Last update: Oct 15, 2024 - Copyright © 2024 Agendize. All rights reserved.