Agendize Developers API

Agendize Client API

Clients/CRM API Reference

On September 1st, 2020 we released the version 2.3 of the Client API. This new version includes performance improvements and a better respect of HTTP protocol for RestFull APIs. If you are currently using the v2.0 of the Online Scheduling API, we encourage you to update to the newer version. If needed, the previous version's documentation is still available here.

The Clients/CRM API empowers you to manage your entire client list and their interactions. This API reference is organized around several objects that can have dependencies with other engagement tools:

Resource representation

{ "id": {string}, "firstName": {string}, "lastName": {string}, "emailAddresses": [ { "email": {string}, "primary": {boolean} } ], "phoneNumbers": [ { "number": {string}, "primary": {boolean}, "mobile": {boolean} } ], "gender": {string}, "timeZone": {string}, "language": {string}, "description": {string}, "picture": { "url": {string}, "mimeType": {string}, "data": {string} }, "address": { "street": {string}, "otherStreet": {string}, "zipCode": {string}, "state": {string}, "city": {string}, "country": {string} }, "extendedProperties": { "private": {object}, "public": {object} }, "externalId": {string}, "companyName": {string}, "title": {string}, "jobTitle": {string}, "webSiteLink": {string}, "additionalAddresses": [ { "street": {string}, "otherStreet": {string}, "zipCode": {string}, "state": {string}, "city": {string}, "country": {string} } ], "relationship": [ { client resource } ], "birthDate": {string}, "additionalFields: [ { "id": {string}, "name": {string}, "value": {string} } ], "explicitConsent": { "date": { dateTime: {string}, timeZone: {string} }, "text": [string] }, "marketingConsent": { "date": { dateTime: {string}, timeZone: {string} }, "text": [string] }, "companies": [ { "id": {string} "name": {string} } ], "marketingOptins: { "email": { "enabled": {boolean}, "clientConsentDate": {string} }, "sms": { "enabled": {boolean} } } }
Parameter name Value Description
id string Identifier of the client.
firstName string First name of the client. Max length: 127.
lastName string Last name of the client. Max length: 127.
emailAddresses[] list Email addresses of the client.
emailAddresses[].email string Email address. Max length: 255.
emailAddresses[].primary boolean Whether the email address is the primary email address of the client.
phoneNumbers(] string Phone numbers of the client.
phoneNumbers[].number string Phone number. Max length: 255.
phoneNumbers[].primary boolean Whether the phone number is the primary phone number of the client.
phoneNumbers[].mobile boolean Whether the phone number is a mobile phone number.
gender string Gender of the client. Values: "male", "female" or "undefined".
timeZone string Time zone of the client. Only if time zone has been specified. Default value: the time zone of the company if the client has been created from an appointment otherwise the time zone of the account.
language string Spoken language of the client. Only if client language has been specified. Default value: the language of the account.
description string Description of the client. Max length: 4GB.
address object Postal address of the client.
address.street string Main street address. Max length: 127.
address.otherStreet string Optional street address Max length: 127..
address.zipCode string Zip code of address. Max length: 127.
address.state string State of address. Max length: 127.
address.city string City of address. Max length: 127.
address.country string Country of address. Max length: 127.
picture object Client picture url and mime type.
picture.url string Url of the client picture.
picture.mimeType string Mime type of the client picture file.
picture.data string Binary data of the client picture file, base64 encoded with Data URI Scheme. Only use with insert and update methods.
tags[] list Tags of the client.
tags[].tag string Text of tag. Max length: 255.
tags[].color boolean Color of tag. Web format (#xxxxxx)
externalId string Unique client identifier from another (external) system. Max length: 65535.
companyName string company name of the client. Max length: 255.
title string Title of the client. Values: "mr" or "mrs", "dr".
jobTitle string Job title of the client. Max length: 255.
webSiteLink string Web site URL of the client. Max length: 255.
additionalAddresses[] list Additional postal address of the client.
additionalAddresses[].street string Main street address. Max length: 255.
additionalAddresses[].otherStreet string Optional street address. Max length: 255.
additionalAddresses[].zipCode string Zip code of address. Max length: 45.
additionalAddresses[].state string State of address. Max length: 100.
additionalAddresses[].city string City of address. Max length: 100.
additionalAddresses[].country string Country of address. Max length: 45.
relationship[] list list of client linked width the current client. Use a client resource.
birthDate string birth date of the client. Format yyyy-MM-dd (year-month-day).
additionalFields list List of fields.
additionalFields[].id string Identifier of the field.
additionalFields[].name string Name of the field.
additionalFields[].value string Value of the field.
explicitConsent object Last client's explicit consent.
explicitConsent.dateTime object Date of the consent.
explicitConsent.date.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information). writable
explicitConsent.date.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company. writable
explicitConsent.text string Text of the consent. Max length: 65535.
marketingConsent object Last client's marketing consent.
marketingConsent.date object Date of the consent.
marketingConsent.date.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information). writable
marketingConsent.date.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company. writable
marketingConsent.text string Text of the consent. Max length: 65535.
companies[] list List of company of the client. writable
companies[].id string Identifier of the company. writable
companies[].name boolean Name of the company
marketingOptins object Marketing opt-ins to receive email and SMS.
marketingOptins.email object Opt-in for email. writable
marketingOptins.email.enabled boolean If the email opt-in is enabled. writable
marketingOptins.date.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information). Read-only
marketingOptins.date.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company. Read-only
marketingOptins.sms object Opt-in for email. Read-only
marketingOptins.sms.enabled boolean If the SMS opt-in is enabled. Read-only

Delete

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

Request

HTTP Request

DELETE https://api.agendize.com/api/2.3/clients/{clientId}

Parameters

Parameter name Value Description
Path parameters
clientId string Client identifier.

Request body

Do not supply a request body with this method.

Response

If successful, this method returns an empty response body.

Get

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

Request

HTTP Request

GET https://api.agendize.com/api/2.3/clients/{clientId}

Parameters

Parameter name Value Description
Path parameters
clientId string Client identifier or externalId.

Request body

Do not supply a request body with this method.

Response

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

List

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

Request

HTTP Request

GET https://api.agendize.com/api/2.3/clients

Parameters

Parameter name Value Description
Optional query parameters
q string Fulltext query on client data fields. Search by first name, last name, phone number and email address. Incompleted value can by used.
maxResults integer The maximum number of entries to return. Max 100 clients per request.
pageToken integer The nextPageToken value returned from a previous call. Requests the next page of clients.
orderBy boolean Sorting criterion (comma separated values if any). The only supported values are id, firstname and lastname.
fields string Returned client fields (comma separated values if any). All clients json fields can be used.
showDeleted boolean Whether to include deleted company list entries in the result. Optional. The default is false.
syncToken string Token obtained from the nextSyncToken field returned on the last page of results from the previous list request. Used to retrieve new and modified clients.

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response body with the following structure:

{ totalItems: {integer}, nextPageToken: {string}, syncToken: {string} items: [Client Resource], }
Parameter name Value Description
totalItems integer Number of total clients.
nextPageToken string Next page token for the next results page.
syncToken string Next sync token.
items string Client resources list.

Insert

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

Request

HTTP Request

POST https://api.agendize.com/api/2.3/clients

Request body

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

Parameter name Value Description
Required Properties
lastName string Last name of the client.
Optional Properties
firstName string First name of the client.
emailAddresses[] list Email addresses of the client.
emailAddresses[].email string Email address.
emailAddresses[].primary boolean Whether the email address is the primary email address of the client.
phoneNumbers(] string Phone numbers of the client.
phoneNumbers[].number string Phone number.
phoneNumbers[].primary boolean Whether the phone number is the primary phone number of the client.
phoneNumbers[].mobile boolean Whether the phone number is a mobile phone number.
gender string Gender of the client. Values: "male", "female" or "undefined".
timeZone string Time zone of the client. Only if time zone has been specified.
language string Spoken language of the client. Only if client language has been specified.
description string Description of the client.
address object Postal address of the client.
address.street string Main street address.
address.otherStreet string Optional street address.
address.zipCode string Zip code of address.
address.state string State of address.
address.city string City of address.
address.country string Country of address.
picture object Client picture url and mime type.
picture.url string Url of the client picture.
picture.mimeType string Mime type of the client picture file.
picture.data string Binary data of the client picture file, base64 encoded with Data URI Scheme. Only use with insert and update methods.
tags[] list Tags of the client.
tags[].tag string Text of tag.
tags[].color boolean Color of tag. Web format (#xxxxxx)
externalId string Unique client identifier from another (external) system.
companyName string company name of the client.
title string Title of the client. Values: "mr" or "mrs", "dr".
jobTitle string Job title of the client.
webSteLink string Web site URL of the client.
marketingOptins object Marketing opt-ins to receive email and SMS.
marketingOptins.email object Opt-in for email. writable
marketingOptins.email.enabled boolean If the email opt-in is enabled. writable
marketingOptins.date.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information). Read-only
marketingOptins.date.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company. Read-only
marketingOptins.sms object Opt-in for email. Read-only
marketingOptins.sms.enabled boolean If the SMS opt-in is enabled. Read-only

Response

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

Advanced search

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

Request

HTTP Request

POST https://api.agendize.com/api/2.3/clients/search

Parameters

Parameter name Value Description
Optional query parameters
maxResults integer The maximum number of entries to return. Max 100 clients per request.
pageToken integer The nextPageToken value returned from a previous call. Requests the next page of clients.
orderBy boolean Sorting criterion (comma separated values if any). The only supported values are id, firstname and lastname.
fields string Returned client fields (comma separated values if any). All clients json fields can be used.

Request body

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

{ "firstName": {string}, "lastName": {string}, "company": {string} "jobTitle": {string}, "externalId": {string}, "street": {string}, "country": {string}, "state": {string}, "zipCode": {string}, "email": {string}, "phone": {phone}, "activityNever": {boolean}, "activityDateMin": {string}, "activityDateMax": {string}, "emailMarketing": {boolean}, "birthDate": {string}, "tags": [ { "id": {string}, "tag": {string} } ], "companies": [ { "id": {string} } ], "language": {string}, "blocked": {boolean}, "misc1": {string}, "misc2": {string}, "misc3": {string}, "misc4": {string}, "misc5": {string}, "misc6": {string}, "misc7": {string}, "misc8": {string}, "misc9": {string}, "misc10": {string} }
Parameter name Value Description
Optional Properties
firstName string Last name of the client.
lastName string Last name of the client.
company string Company of the client.
jobTitle string Last name of the client to search.
externalId string Last name of the client to search.
street string Main street and optional street address of the client.
country string Country of address of the client.
state string State of address of the client.
zipCode string Zip code of address of the client .
city string City of address of the client.
email string Email address of the client.
phone string Phone number client to search.
activityNever boolean Last activity of the client. Default value: false. If set to true, activityDateMin and activityDateMax are disabled.
activityDateMin string Activity min date time as a combined date-time value (formatted according to RFC 3339, without time zone information).
activityDateMax string Activity max date time as a combined date-time value (formatted according to RFC 3339, without time zone information).
emailMarketing boolean If the client has a marketing email opt-in. Default value: false
birthDate string Birth date of the client as a date value (formatted according to RFC 3339, without time zone information).
tags list List of tags. You can define only id or tag property.
tags[].id string Identifier of the tag.
tags[].tag string Identifier of the tag.
companies list List of companies. You can define only one company.
companies[].id string Identifier of the companies.
language string Language of the client.
blocked boolean If the client is blocked.
misc[1...10] string/integer/boolean/float Custom misc fields.

Response

If successful, this method returns a response body with the following structure:

{ totalItems: {integer}, nextPageToken: {string}, items: [Client Resource], }
Parameter name Value Description
totalItems integer Number of total clients.
nextPageToken string Next page token for the next results page.
syncToken string Next sync token.
items string Client resources list.

Update

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

Request

HTTP Request

PUT https://api.agendize.com/api/2.3/clients/{clientId}

Parameters

Parameter name Value Description
Path parameters
clientId string Client identifier or externalId.

Request body

In the request body, supply a Client resource with the following properties:

Parameter name Value Description
Optional Properties
firstName string First name of the client.
lastName string Last name of the client.
emailAddresses[] list Email addresses of the client.
emailAddresses[].email string Email address.
emailAddresses[].primary boolean Whether the email address is the primary email address of the client.
phoneNumbers(] string Phone numbers of the client.
phoneNumbers[].number string Phone number.
phoneNumbers[].primary boolean Whether the phone number is the primary phone number of the client.
phoneNumbers[].mobile boolean Whether the phone number is a mobile phone number.
gender string Gender of the client. Values: "male", "female" or "undefined".
timeZone string Time zone of the client. Only if time zone has been specified.
language string Spoken language of the client. Only if client language has been specified.
description string Description of the client.
address object Postal address of the client.
address.street string Main street address.
address.otherStreet string Optional street address.
address.zipCode string Zip code of address.
address.state string State of address.
address.city string City of address.
address.country string Country of address.
picture object Client picture url and mime type.
picture.mimeType string Mime type of the client picture file.
picture.data string Binary data of the client picture file, base64 encoded with Data URI Scheme. Only use with insert and update methods.
tags[] list Tags of the client.
tags[].tag string Text of tag.
tags[].color boolean Color of tag. Web format (#xxxxxx)
externalId string Unique client identifier from another (external) system.
companyName string company name of the client.
title string Title of the client. Values: "mr" or "mrs", "dr".
jobTitle string Job title of the client.
webSiteLink string Web site URL of the client.
marketingOptins object Marketing opt-ins to receive email and SMS.
marketingOptins.email object Opt-in for email. writable
marketingOptins.email.enabled boolean If the email opt-in is enabled. writable
marketingOptins.date.dateTime string The time, as a combined date-time value (formatted according to RFC 3339, without time zone information). Read-only
marketingOptins.date.timeZone string The time zone. Possible values can be found here. The default value is the time zone of the company. Read-only
marketingOptins.sms object Opt-in for email. Read-only
marketingOptins.sms.enabled boolean If the SMS opt-in is enabled. Read-only

Response

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

Watch

Watch for changes to clients.

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

The watch sends a Client resource in the request body

Request

HTTP Request

POST https://api.agendize.com/api/2.3/clients/watch

Request body

{ "address": {string}, "name": {string}, "basicAuth": { "username": {string}, "password": {string} }, "httpRequestHeader": { {name}: {string} }, "schema": {object} "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.
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 events supported

  • Client added in dashboard. In this case, the watch request adds the following header property in the HTTP request:
    X-Agendize-objectEvent: created
  • Client modified in dashboard. In this case, the watch request adds the following header property in the HTTP request:
    X-Agendize-objectEvent: updated
  • Client modified in dashboard. In this case, the watch request adds the following header property in the HTTP request:
    X-Agendize-objectEvent: deleted

Agendize | Support | Status

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