Profile Management (Dec 3, 2024, 10:16:51 AM)

Download OpenAPI specification:Download

Welcome to Synerise API Reference! We hope that you'll enjoy your stay here.

If you need help with our services, feel free to contact us at support@synerise.com.

Authentication

JWT

Synerise uses JSON Web Token (JWT) as the authorization method. The token is generated by the auth/login endpoint. You need to include it in the Authorization header of your requests, with a Bearer prefix. See this simplified example of a call:

curl -X GET https://api.synerise.com/v4/clients \
-H 'Accept: application/json' \
-H 'Api-Version: 4.4' \
-H 'Authorization: Bearer eyJhbGdiOiJSzZXIaLCJjdGQiOjE1NTI0NjMzMjg4NjIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsIm5tZSI' \
-H 'Content-Type: application/json'

Remember to include a space between Bearer and the token.

By default, the token is valid for one week (see workspace settings). You can request a refreshed key for the session by using the auth/refresh endpoint before the current token expires.

You can verify your JWT signature by using the public key.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

TrackerKey

Authorization by tracker key sent in a token query parameter. This may be the same key as used in the tracking code of the website. For details, see this article: https://help.synerise.com/developers/web/installation-and-configuration/#creating-a-tracking-code.

Security Scheme Type	API Key
Query parameter name:	token

Authorization

Methods to authorize and obtain JWT token required by our API endpoints

Log in as User

Authenticate as a User.

Note: To perform operations within a Workspace, you must select a Workspace.

This method does not require a Synerise authorization token.

Request Body schema: application/json

username required	string The login (email address) of the user
password required	string The user's password
deviceId	string Identifier of user's current device
externalProviderToken	string
externalProviderType	string Value: "GOOGLE"

Responses

Request samples

Content type

application/json

{"username": "string",
"password": "string",
"deviceId": "string",
"externalProviderToken": "string",
"externalProviderType": "GOOGLE"
}

Response samples

200

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Verify User multi-factor authentication

Authenticate as a User with multi-factor authentication.

Note: To perform operations within a Workspace, you must select a Workspace.

API consumer who can use this method: Synerise User
This method is available to all authenticated users, before and after multi-factor authentication is confirmed.

Authorizations:

JWT

query Parameters

mfaType

required

string

Enum: "TOTP_AUTHENTICATOR" "EMAIL"

Type of multi-factor authentication

Request Body schema: application/json

verificationCode required	string Multi-factor verification code
deviceId	string
externalProviderToken	string
externalProviderType	string Value: "GOOGLE"

Responses

Request samples

Content type

application/json

{"verificationCode": "string",
"deviceId": "string",
"externalProviderToken": "string",
"externalProviderType": "GOOGLE"
}

Response samples

200

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Select Workspace

After logging in as a User, select a Workspace where you want to perform operations.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

path Parameters

businessProfileUUID

required

string <uuid>

UUID of the workspace

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/uauth/auth/login/user/profile/%7BbusinessProfileUUID%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
423

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Get Workspaces

Retrieve a list of Workspaces available to the user.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/uauth/business-profile/ 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"businessProfileGuid": "string",
"logo": "string",
"name": "string",
"id": 0,
"created": "2019-08-24T14:15:22Z",
"subdomain": "string",
"ipRestricted": true,
"mfaRequired": true
}
]

Get current Workspace

Retrieve information about the currently selected workspace.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/uauth/business-profile/current 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"selected": true,
"data": {"id": 0,
"name": "string",
"logo": "string",
"businessProfileGuid": "string",
"created": "2019-08-24T14:15:22Z",
"subdomain": "string",
"ipRestriction": "OFF",
"mfaRestriction": "OFF"
}
}

Log in as Workspace

Obtain a new Workspace JWT Token.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey

required

string

Workspace API key

WARNING: Workspace API keys can be used to access all customer data and manage the workspace. They should only be used for server-to-server communication in integrations. DO NOT use workspace API keys in your mobile applications or websites.

Responses

Request samples

Content type

application/json

{"apiKey": "64c09614-1b2a-42f7-804d-f647243eb1ab"
}

Response samples

200
400
401

Content type

application/json

{"token": "string"
}

Refresh a Profile token

Retrieve a refreshed JWT Token to prolong the session.

The current token must still be active at the time of the request.

API consumers who can use this method: Profile (formerly client), Anonymous profile (formerly client)
This method does not require a Synerise authorization token.

Authorizations:

JWT

Request Body schema: application/json

apiKey

required

string

Profile (formerly "Client") API key

Responses

Request samples

Content type

application/json

{"apiKey": "string"
}

Response samples

200
401

Content type

application/json

{"token": "string",
"expiration": 1649283173,
"created": 1649277173668,
"origin": "SYNERISE",
"customId": "card123",
"realm": "client"
}

Authenticate as Profile

Obtain a new JWT for a Profile. If an account for the Profile does not exist and the identityProvider is different than SYNERISE, this request creates an account.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey required	string Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Authenticate Profile with a server

Obtain a new JWT for a Profile. This method is designed to be used from a backend server that handles login requests and communicates with Synerise to execute them.
If an account for the Profile does not exist and the identityProvider is different than SYNERISE, this request creates an account.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_SERVER_LOGIN_CLIENT_CREATE

Request Body schema: application/json

ipAddress required	string The IP address of the client device that is logging in.
apiKey required	string Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"ipAddress": "string",
"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Authenticate as Profile (conditional)

Obtain a new JWT token for a Profile.

If the account does not exist, an account is not created.
If any additional conditions are required for logging in, the response is HTTP200 and lists the conditions.
Note that using this endpoint requires authenticating as an anonymous Profile first.
This method does not require a Synerise authorization token.

Authorizations:

JWT

Request Body schema: application/json

apiKey required	string Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

Content type

application/json

{"conditions": ["string"
],
"status": "SUCCESS",
"token": "string",
"expiration": 1649283173,
"created": 1649277173668,
"origin": "SYNERISE",
"customId": "card123",
"realm": "client"
}

Authenticate anonymously

Obtain a new JWT for an anonymous Profile. The token can be used and refreshed in the same way as tokens of registered Profiles.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey required	string Profile (formerly "Client") API key
uuid required	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique iOS or Android device identifier.

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"deviceId": "string"
}

Response samples

200
401

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Profile registration

Register and confirm profile accounts (no third-party auth)

Register a Profile

Create a new account for a Profile. This account is owned by the Profile and can be accessed and edited by it. If you don't have some information about the profile, don't insert a null-value parameter - omit the parameter entirely.

API consumers who can use this method: Anonymous profile (formerly client), Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_REGISTER_CLIENT_CREATE

Authorizations:

JWT

Request Body schema: application/json

email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
password	string Password for the Profile
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
displayName	string Currently unused
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"email": "string",
"password": "string",
"phone": "+48111222333",
"customId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"avatarUrl": "string",
"birthDate": "1987-10-24",
"company": "string",
"city": "string",
"address": "string",
"zipCode": "string",
"province": "string",
"countryCode": "PL",
"sex": "FEMALE",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

400
401
403
424

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string",
"errorCode": "string"
}

Confirm registration with PIN code

Confirm account registration with PIN code received by email (code is sent automatically at registration).

API consumer who can use this method: Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_PIN_CODE_CONFIRMATION_CLIENT_CREATE

Authorizations:

JWT

Request Body schema: application/json

deviceId	string Unique Android or iOS device ID
email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
pinCode	string The PIN code received by email
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`

Responses

Request samples

Content type

application/json

{"deviceId": "string",
"email": "string",
"pinCode": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f"
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string",
"errorCode": "string"
}

Re-send PIN code

Re-send a PIN code to the Profile's email.

API consumer who can use this method: Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_PIN_CODE_RESEND_CLIENT_CREATE

Authorizations:

JWT

Request Body schema: application/json

email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
deviceId	string Unique Android or iOS device ID
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`

Responses

Request samples

Content type

application/json

{"email": "string",
"deviceId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f"
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string",
"errorCode": "string"
}

Activate a Profile's account

Activate the Profile's account. This is used when registration is configured to keep the account inactive until the email is confirmed.

API consumers who can use this method: Profile (formerly client), Anonymous profile (formerly client), Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_CONFIRMATION_CLIENT_CREATE

Authorizations:

JWT

Request Body schema: application/json

token

string

Activation token received by email

Responses

Request samples

Content type

application/json

{"token": "8a0be35a-f6be-437b-ab18-339cc6194df5"
}

Response samples

400
401
403
409
500

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string",
"errorCode": "string"
}

Re-send email confirmation

Request a re-sending of the confirmation email.

API consumers who can use this method: Profile (formerly client), Anonymous profile (formerly client), Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_CONFIRMATION_CLIENT_CREATE

Authorizations:

JWT

Request Body schema: application/json

email	string Email address
deviceId	string Unique Android or iOS device ID
uuid	string UUID of the Client

Responses

Request samples

Content type

application/json

{"email": "string",
"deviceId": "string",
"uuid": "string"
}

Response samples

401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Profile management

Manage Profile details

List profiles

Retrieve a list of Profiles. You can filter, sort, and paginate the results.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_LIST_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

query Parameters

sortBy	string Enum: "firstName" "lastName" "lastActivityDate" "email" "city" "phone" Example: sortBy=firstName Profile attribute by which the list will be sorted
sortOrder	string Enum: "ASC" "DESC" Sorting order
pageIndex	integer <int32> >= 1 Number of pages to retrieve
pageSize	integer <int32> >= 1 Number of entries on a page
filters[anonymous]	boolean When set to `true`, only anonymous profiles are listed
filters[firstName]	string Example: filters[firstName]=John Filter profiles by first name
filters[lastName]	string Example: filters[lastName]=Smith Filter profiles by last name
filters[email]	string Example: filters[email]=person@example.com Filter profiles by email
filters[phone]	string Example: filters[phone]=123456789 Filter profiles by phone

header Parameters

Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/v4/clients?sortBy=firstName&sortOrder=SOME_STRING_VALUE&pageIndex=SOME_INTEGER_VALUE&pageSize=SOME_INTEGER_VALUE&filters%5Banonymous%5D=SOME_BOOLEAN_VALUE&filters%5BfirstName%5D=John&filters%5BlastName%5D=Smith&filters%5Bemail%5D=person%40example.com&filters%5Bphone%5D=123456789' 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

200
400
401
403
415

Content type

application/json

[{"clientId": 0,
"email": "string",
"phone": "+48111222333",
"customId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"company": "string",
"address": "string",
"city": "string",
"province": "string",
"zipCode": "string",
"countryCode": "PL",
"birthDate": "1987-10-24",
"sex": "FEMALE",
"avatarUrl": "string",
"anonymous": false,
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
],
"previousClients": [0
],
"lastActivityDate": "2019-03-19T14:05:39Z"
}
]

Create a Profile

Create a new profile in the Synerise application database. If you don't have some information about the profile, don't insert a null-value parameter - omit the parameter entirely.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_CLIENT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_MANAGEMENT

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

In the request body, you must provide at least one of those identifiers:

email
If non-unique emails are enabled, email is NOT an identifier.
phone
Phone is treated as an identifier only if no other identifier is provided. If this is the case and non-unique emails are disabled, an anonymous profile is created with a randomized email placeholder.
customId
uuid

email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
displayName	string Currently unused
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"email": "string",
"phone": "+48111222333",
"customId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"avatarUrl": "string",
"birthDate": "1987-10-24",
"company": "string",
"city": "string",
"address": "string",
"zipCode": "string",
"province": "string",
"countryCode": "PL",
"sex": "FEMALE",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

400
401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2019-03-18T13:15:39.84Z",
"path": "/clients",
"message": "Some fields did not pass validation",
"errors": [{"code": 12082,
"field": "countryCode",
"message": "Country Code must have 0 or 3 characters as per ISO format.",
"rejectedValue": "string"
},
{"code": 120,
"field": "avatarUrl",
"message": "120",
"rejectedValue": "string"
}
]
}

Create a company profile in CRM

Create a new profile that is marked as a company in the Synerise application database.

You must provide at least one of those identifiers: email, phone, customId, uuid.

Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native).

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_CLIENT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_MANAGEMENT

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

In the request body, you must provide at least one of those identifiers:

email
If non-unique emails are enabled, email is NOT an identifier.
phone
Phone is treated as an identifier only if no other identifier is provided. If this is the case and non-unique emails are disabled, an anonymous profile is created with a randomized email placeholder.
customId
uuid

email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
displayName	string Currently unused
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"email": "string",
"phone": "+48111222333",
"customId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"avatarUrl": "string",
"birthDate": "1987-10-24",
"company": "string",
"city": "string",
"address": "string",
"zipCode": "string",
"province": "string",
"countryCode": "PL",
"sex": "FEMALE",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

400
401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2019-03-18T13:15:39.84Z",
"path": "/clients",
"message": "Some fields did not pass validation",
"errors": [{"code": 12082,
"field": "countryCode",
"message": "Country Code must have 0 or 3 characters as per ISO format.",
"rejectedValue": "string"
},
{"code": 120,
"field": "avatarUrl",
"message": "120",
"rejectedValue": "string"
}
]
}

Delete a company profile

Delete a company profile from the database.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_ID_CLIENT_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Example: 434428563

The ID of the profile

header Parameters

Accept required	string Value: "application/json"
Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/v4/company-clients/%7BclientId%7D 
  --header 'Accept: SOME_STRING_VALUE' 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

401
403
404
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-29T13:08:16.235Z",
"path": "/exampleEndpoint",
"message": "Some fields did not pass validation",
"errors": [{"code": 120,
"field": "exampleField",
"message": "120",
"rejectedValue": "exampleValue"
}
]
}

Merge profiles by customId

Moves profile UUIDs to a single profile (which must already exist) and removes the profiles that were merged.

The event history of the source profiles is moved to the target profile.

The attributes (data from the attributes object) that don't exist in the target profile are copied to the target profile. If an attribute already exists in the target profile, the value from the source profile is lost.

The properties and tags of the source profiles are lost, even if they don't have a value in the target profile.

WARNING: This operation is irreversible. Use it carefully.

WARNING: You should not try to merge more than 10-20 profiles at once.

For more details, see the Developer Guide.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_MERGEBYCUSTOMID_CLIENT_UPDATE

Authorizations:

JWT

path Parameters

sourceCustomIDs required	string Example: customIdExample,customIdExample2,customIdExample3,customIdExample4,customIdExample5 Comma-delimited string with custom IDs of the profiles to merge
targetCustomID required	string Example: customIdExample The custom ID of the profile to merge the `sourceCustomIDs` into

header Parameters

Accept required	string Value: "application/json"
Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/v4/clients/merge/from/custom-ids/%7BsourceCustomIDs%7D/to/custom-id/%7BtargetCustomID%7D 
  --header 'Accept: SOME_STRING_VALUE' 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

200
401
403
404

Content type

application/json

{"clientId": 0,
"email": "string",
"phone": "+48111222333",
"customId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"company": "string",
"address": "string",
"city": "string",
"province": "string",
"zipCode": "string",
"countryCode": "PL",
"birthDate": "1987-10-24",
"sex": "FEMALE",
"avatarUrl": "string",
"anonymous": false,
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
],
"previousClients": [0
],
"lastActivityDate": "2019-03-19T14:05:39Z"
}

Merge profiles by clientId

Moves profile UUIDs to a single profile (which must already exist) and removes the profiles that were merged.

The event history of the source profiles is moved to the target profile.

The attributes (data from the attributes object) that don't exist in the target profile are copied to the target profile. If an attribute already exists in the target profile, the value from the source profile is lost.

The properties and tags of the source profiles are lost, even if they don't have a value in the target profile.

WARNING: This operation is irreversible. Use it carefully.

WARNING: You should not try to merge more than 10-20 profiles at once.

For more details, see the Developer Guide.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_MERGE_BY_ID_CLIENT_UPDATE

Authorizations:

JWT

path Parameters

fromClientIds required	string Example: 434428563,33322211,232212342 Comma-delimited string with client IDs of the profiles to merge
toClientId required	integer <int64> Example: 434428563 The ID of the profile to merge the `fromClientIds` into

header Parameters

Accept required	string Value: "application/json"
Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/v4/clients/merge/from/ids/%7BfromClientIds%7D/to/id/%7BtoClientId%7D 
  --header 'Accept: SOME_STRING_VALUE' 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

200
401
403
404

Content type

application/json

{"clientId": 0,
"email": "string",
"phone": "+48111222333",
"customId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"company": "string",
"address": "string",
"city": "string",
"province": "string",
"zipCode": "string",
"countryCode": "PL",
"birthDate": "1987-10-24",
"sex": "FEMALE",
"avatarUrl": "string",
"anonymous": false,
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
],
"previousClients": [0
],
"lastActivityDate": "2019-03-19T14:05:39Z"
}

Batch add or update profiles

Enqueue a number of add/update operations in the Synerise application database.

If you don't have some information about a profile, don't insert a null-value parameter - omit the parameter entirely. Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native).

The body contains an array of objects to update. The objects are the same as in the Create a Profile and Update a Profile endpoints.

IMPORTANT: The request body cannot contain more than 1000 items or exceed 1 MB in size.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BATCH_CLIENT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_MANAGEMENT

Authorizations:

JWT

header Parameters

Accept required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Request Body schema: application/json

Each profile must have at least one of the following identifiers:

email
If non-unique emails are enabled, email is NOT an identifier.
phone
Phone number is treated as an identifier only if no other identifier is provided. Then, if a profile with this phone number does not exist and non-unique emails are disabled, an anonymous profile is created.
customId
uuid
clientId (can be used only when updating an existing profile)

Array ([ 1 .. 1000 ] items)

clientId	integer <int64> This ID can be used only for updating an existing profile. If a profile does not exist and `clientId` is the only provided identifier, the operation returns HTTP 202 and a profile is not created. If another identifier is provided, a profile is created with that identifier and a `clientId` generated by the system.
email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
displayName	string Currently unused
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

[{"clientId": 0,
"email": "string",
"phone": "+48111222333",
"customId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"avatarUrl": "string",
"birthDate": "1987-10-24",
"company": "string",
"city": "string",
"address": "string",
"zipCode": "string",
"province": "string",
"countryCode": "PL",
"sex": "FEMALE",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}
]

Response samples

207
401
403
415

Content type

application/json

[{"rejectedValue": "de73b3490c4-bb8c0d8",
"field": "list[0].uuid",
"status": 400,
"message": "UUID must be well-formed value as per RFC 4122"
}
]

Get profile data

Retrieve profile data by profile ID.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_ID_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Example: 434428563

The ID of the profile

header Parameters

Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/v4/clients/%7BclientId%7D 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

200
401
403
404

Content type

application/json

{"clientId": 0,
"email": "string",
"phone": "+48111222333",
"customId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"company": "string",
"address": "string",
"city": "string",
"province": "string",
"zipCode": "string",
"countryCode": "PL",
"birthDate": "1987-10-24",
"sex": "FEMALE",
"avatarUrl": "string",
"anonymous": false,
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
],
"previousClients": [0
],
"lastActivityDate": "2019-03-19T14:05:39Z"
}

Update a profile (identify by ID)

Change the details of a profile in the Synerise application database.

Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native).

The attributes object can be used to add custom attributes of your choice. For example, "hasDog":true.

The tags array contains custom tags of your choice.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_ID_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Example: 434428563

The ID of the profile

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
displayName	string Currently unused
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"email": "string",
"phone": "+48111222333",
"customId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"avatarUrl": "string",
"birthDate": "1987-10-24",
"company": "string",
"city": "string",
"address": "string",
"zipCode": "string",
"province": "string",
"countryCode": "PL",
"sex": "FEMALE",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

400
401
403
404
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2019-03-21T08:37:34.526Z",
"path": "/clients/1234",
"message": "Some fields did not pass validation",
"errors": [{"code": 12053,
"field": "uuid",
"message": "UUID must be well-formed value as per RFC 4122",
"rejectedValue": "4321"
}
]
}

Delete a profile

Delete a profile from the database.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_ID_CLIENT_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Example: 434428563

The ID of the profile

header Parameters

Accept required	string Value: "application/json"
Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/v4/clients/%7BclientId%7D 
  --header 'Accept: SOME_STRING_VALUE' 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

401
403
404

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-29T13:08:16.235Z",
"path": "/exampleEndpoint",
"message": "Some fields did not pass validation",
"errors": [{"code": 120,
"field": "exampleField",
"message": "120",
"rejectedValue": "exampleValue"
}
]
}

Update a profile (identify by email)

Change the details of a profile in the Synerise application database.

Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native).

The attributes object can be used to add custom attributes of your choice. For example, "hasDog":true.

The tags array contains custom tags of your choice.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_EMAIL_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientEmail

required

string

Example: clientemail@synerise.com

The profile's email address

Must match the pattern (ECMA flavor): /^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/
The value can't include any characters that match the patternn (ECMA flavor): /([\uD800-\uDBFF][\uDC00-\uDFFF])|([\r\n\u2028\u2029\u00AD]|[\uFE00-\uFE0F]|[\u0000])/

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
displayName	string Currently unused
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"email": "string",
"phone": "+48111222333",
"customId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"avatarUrl": "string",
"birthDate": "1987-10-24",
"company": "string",
"city": "string",
"address": "string",
"zipCode": "string",
"province": "string",
"countryCode": "PL",
"sex": "FEMALE",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

400
401
403
404
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2019-03-21T08:37:34.526Z",
"path": "/clients/by-email/client@synerise.com",
"message": "Some fields did not pass validation",
"errors": [{"code": 12053,
"field": "uuid",
"message": "UUID must be well-formed value as per RFC 4122",
"rejectedValue": "4321"
}
]
}

Update a profile (identify by customId)

Change the details of a profile in the Synerise application database.

Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native).

The attributes object can be used to add custom attributes of your choice. For example, "hasDog":true.

The tags array contains custom tags of your choice.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_CUSTOM_ID_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

customId

required

string

Example: customIdExample

The custom ID of the profile

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
displayName	string Currently unused
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"email": "string",
"phone": "+48111222333",
"customId": "string",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"avatarUrl": "string",
"birthDate": "1987-10-24",
"company": "string",
"city": "string",
"address": "string",
"zipCode": "string",
"province": "string",
"countryCode": "PL",
"sex": "FEMALE",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

400
401
403
404
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2019-03-21T08:37:34.526Z",
"path": "/clients/by-customid/customId1234",
"message": "Some fields did not pass validation",
"errors": [{"code": 12053,
"field": "uuid",
"message": "UUID must be well-formed value as per RFC 4122",
"rejectedValue": "4321"
}
]
}

Delete a profile (identify by customId)

Delete a profile from the database.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_ID_CLIENT_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

customId

required

string

Example: customIdExample

The custom ID of the profile

header Parameters

Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/v4/clients/by-custom-id/%7BcustomId%7D 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

401
403
404

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-29T13:08:16.235Z",
"path": "/exampleEndpoint",
"message": "Some fields did not pass validation",
"errors": [{"code": 120,
"field": "exampleField",
"message": "120",
"rejectedValue": "exampleValue"
}
]
}

Fetch profile data

Get the details of a single profile. If no profile is found, HTTP 404 is returned.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_IDENTIFIER_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

identifierType required	string Enum: "by-custom-id" "by-phone" "by-uuid" "by-email" Example: by-email The type of profile identifier to use for the request
identifierValue required	string Example: address@domain.com The value of the selected identifier

header Parameters

Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/v4/clients/%7BidentifierType%7D/%7BidentifierValue%7D 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type

application/json

{"clientId": 0,
"email": "string",
"phone": "+48111222333",
"customId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"company": "string",
"address": "string",
"city": "string",
"province": "string",
"zipCode": "string",
"countryCode": "PL",
"birthDate": "1987-10-24",
"sex": "FEMALE",
"avatarUrl": "string",
"anonymous": false,
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
],
"previousClients": [0
],
"lastActivityDate": "2019-03-19T14:05:39Z"
}

Create profile export task for segmentation

Create an export task. The data is later retrieved using this endpoint. The data is materialized at the time of export's creation, not at the time of retrieval.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CLIENT_EXPORTER_REPORT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: SETTINGS_EXPORT

Authorizations:

JWT

Request Body schema: application/json

Segmentation request body

name required	string The name of the export
fields required	Array of strings An array of fields from the profile to include in the export
agreementFilter required	string Enum: "NONE" "RECOGNIZED" "ANONYMOUS" Filter exported profiles by status: only anonymous, only recognized, or no filter
segmentationHash required	string Segmentation (UUID) to export profiles from
expressions	Array of strings An array of expressions (expression UUIDs) whose results will be included in the export. In the export results, the result of the analysis is identified by the UUID.
aggregates	Array of strings An array of aggregates (aggregate UUIDs) whose results will be included in the export. In the export results, the result of the analysis is identified by the UUID.
excludedIds required	Array of integers <= 0 items [ items ] Necessary for backwards compatibility. Send empty array.

Responses

Request samples

Content type

application/json

{"name": "Sample export",
"fields": ["firstname"
],
"agreementFilter": "NONE",
"segmentationHash": "a0640816-8092-4a17-b41e-cd9e1230a3c7",
"expressions": ["1e5d5fde-4abf-48d5-b3bd-33e1babbc646"
],
"aggregates": ["dc8de7ff-2cf2-4ccd-900e-3c8bd4631f00"
],
"excludedIds": [ ]
}

Response samples

200

Content type

application/json

{"taskId": 546,
"columnOrder": ["id",
"firstname"
],
"estimatedCount": 6743,
"ttl": "2h"
}

Retrieve export data

Retrieve data from an export created before. The data is materialized at the time of export's creation, not at the time of retrieval.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CLIENT_EXPORTER_REPORT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: SETTINGS_EXPORT

Authorizations:

JWT

path Parameters

taskId

required

integer

Example: 546

The ID of the export task to retrieve the results from

query Parameters

limit	integer <= 10000 The limit of results retrieved. Used for pagination.
offset	integer The index of the first result to retrieve. The first result has the index `0`. Used for pagination.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/client-exporter/v2/export/clients/task/%7BtaskId%7D?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"id": 123,
"name": "John",
"email": "john@synerise.pl"
}
]

Get Profile details

Retrieve the details of a Profile.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_DETAILS_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/crm/v1/clients/%7BclientId%7D/contacts 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"base": {"property1": {"label": "string",
"value": null
},
"property2": {"label": "string",
"value": null
}
},
"tags": ["string"
]
}

Update Profile

Update a Profile.

Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native).

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_MANAGEMENT

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

Request Body schema: application/json

id	integer ID of the Profile
uuid	string UUID of the Profile
anonymous_type	string If the Profile is anonymous, this field defines how they are identified
email	string Profile's e-mail address
firstname	string Profile's first name
lastName	string Profile's last name
custom_identify	string A custom ID for the Profile
company	string Profile's company
phone	string Profile's phone number
address	string Profile's street address
birthdate	string Profile's date of birth
city	string Profile's city of residence
zipCode	string Profile's zip code
province	string Profile's province of residence
country_id	string ID of the Profile's country of residence
countryCode	string Code of Profile's country of residence
avatarUrl	string or null URL of the Profile's avatar picture
sex	string Enum: "FEMALE" "MALE" "UNDEFINED" Profile's sex
last_activity_date	string <date> Date of Profile's last activity
created	string <date> Date when the Profile was created
updated	string <date> Date when the Profile account was last updated
deletedAt	string <date> Date when the Profile account was deleted
tags	Array of strings Custom tags. They can be used, for example, to group Profiles.

Responses

Request samples

Content type

application/json

{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}

Response samples

200

Content type

application/json

{"base": {"property1": {"label": "string",
"value": null
},
"property2": {"label": "string",
"value": null
}
},
"tags": ["string"
]
}

List Profiles

Retrieve a list of profiles. You can sort and filter the results.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

query Parameters

limit	integer <int32> Default: 25 The maximum number of items to retrieve. This can be used for pagination.
offset	integer <int32> Default: 0 The ID of the first item to retrieve. This is used for pagination. For example, to retrieve items starting at number 11, set offset to 10.
recognized	string Default: "NONE" Enum: "RECOGNIZED" "true" "ANONYMOUS" "false" "NONE" Filter the results by Profile's anonymity status. `true` is the same as `RECOGNIZED`. `false` is the same as `ANONYMOUS`. When set to `NONE`, no filter is applied.
search	stringfield:value Example: search=firstName:John Filter the results by parameter values. `field` is the name of a field in the Profile. If you enter a simple string (not a `field:value` pattern), the search will take the following parameters into account: email, first name, last name, UUID, custom parameters.
sortBy	stringfield:orderType Choose a parameter to sort the results. `field` is the name of a field in the Profile. `orderType` can be `ASC` or `DESC`.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/crm/v1/list?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE&recognized=SOME_STRING_VALUE&search=firstName%3AJohn&sortBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"customers": [{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}
],
"all": 0,
"limit": 0,
"offset": 0,
"matching": 0
}

Get autocomplete suggestions

Get autocomplete suggestions for a Profile search. The suggestions are ordered by relevance.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_AUTOCOMPLETE_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

query Parameters

field required	string Example: field=lastName The field to get suggestions from
prefix required	string Prefix that triggers this autocomplete rule
limit	integer Default: 10 The maximum number of suggestions to retrieve

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/crm/v1/autocomplete?field=lastName&prefix=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"entries": ["string"
]
}

Update Profile identified as company

Update a company Profile. Do not send null-values for already existing fields that you do not want to change, they will be overwritten.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_MANAGEMENT

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

Request Body schema: application/json

id	integer ID of the Profile
uuid	string UUID of the Profile
anonymous_type	string If the Profile is anonymous, this field defines how they are identified
email	string Profile's e-mail address
firstname	string Profile's first name
lastName	string Profile's last name
custom_identify	string A custom ID for the Profile
company	string Profile's company
phone	string Profile's phone number
address	string Profile's street address
birthdate	string Profile's date of birth
city	string Profile's city of residence
zipCode	string Profile's zip code
province	string Profile's province of residence
country_id	string ID of the Profile's country of residence
countryCode	string Code of Profile's country of residence
avatarUrl	string or null URL of the Profile's avatar picture
sex	string Enum: "FEMALE" "MALE" "UNDEFINED" Profile's sex
last_activity_date	string <date> Date of Profile's last activity
created	string <date> Date when the Profile was created
updated	string <date> Date when the Profile account was last updated
deletedAt	string <date> Date when the Profile account was deleted
tags	Array of strings Custom tags. They can be used, for example, to group Profiles.

Responses

Request samples

Content type

application/json

{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}

Response samples

200

Content type

application/json

{"base": {"property1": {"label": "string",
"value": null
},
"property2": {"label": "string",
"value": null
}
},
"tags": ["string"
]
}

Identify Profile as a company

Identifies a Profile as a company.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_MANAGEMENT

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/crm/v1/company-clients/%7BclientId%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"base": {"property1": {"label": "string",
"value": null
},
"property2": {"label": "string",
"value": null
}
},
"tags": ["string"
]
}

Get details of Profile identified as company

Retrieve the details of a company Profile.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_DETAILS_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/crm/v1/company-clients/%7BclientId%7D/contacts 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"base": {"property1": {"label": "string",
"value": null
},
"property2": {"label": "string",
"value": null
}
},
"tags": ["string"
]
}

List Profiles identified as companies

Retrieve a detailed list of Profiles that are identified as companies.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

query Parameters

limit	integer <int32> Default: 25 The maximum number of items to retrieve. This can be used for pagination.
offset	integer <int32> Default: 0 The ID of the first item to retrieve. This is used for pagination. For example, to retrieve items starting at number 11, set offset to 10.
recognized	string Default: "NONE" Enum: "RECOGNIZED" "true" "ANONYMOUS" "false" "NONE" Filter the results by Profile's anonymity status. `true` is the same as `RECOGNIZED`. `false` is the same as `ANONYMOUS`. When set to `NONE`, no filter is applied.
sortBy	stringfield:orderType Choose a parameter to sort the results. `field` is the name of a field in the Profile. `orderType` can be `ASC` or `DESC`.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/crm/v1/company-clients?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE&recognized=SOME_STRING_VALUE&sortBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"customers": [{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}
],
"all": 0,
"limit": 0,
"offset": 0,
"matching": 0
}

List Profiles from company

Retrieve a list of Profiles assigned to a company.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permissions required: CRM_LIST_CLIENT_READ, CRM_DETAILS_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

query Parameters

limit	integer <int32> Default: 25 The maximum number of items to retrieve. This can be used for pagination.
offset	integer <int32> Default: 0 The ID of the first item to retrieve. This is used for pagination. For example, to retrieve items starting at number 11, set offset to 10.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/crm/v1/company-clients/%7BclientId%7D/relations?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"customers": [{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}
],
"all": 0,
"limit": 0,
"offset": 0,
"matching": 0
}

Get Profile's company

Retrieve the company that a Profile is assigned to.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_DETAILS_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/crm/v1/clients/%7BclientId%7D/company 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

"string"

Gets company identifier attribute

Retrieve the name of the attribute that is used to identify company-type Profiles.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/crm/v1/company-clients-identifier 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

"string"

Get Profiles from local segmentation

Retrieve a list of Profiles from a local (ad-hoc) segmentation.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_FROM_LOCAL_SEGMENTATION_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

path Parameters

UUID

required

string <uuid>

Local segmentation UUID

query Parameters

limit	integer <int32> Default: 25 The maximum number of items to retrieve. This can be used for pagination.
offset	integer <int32> Default: 0 The ID of the first item to retrieve. This is used for pagination. For example, to retrieve items starting at number 11, set offset to 10.
recognized	string Default: "NONE" Enum: "RECOGNIZED" "true" "ANONYMOUS" "false" "NONE" Filter the results by Profile's anonymity status. `true` is the same as `RECOGNIZED`. `false` is the same as `ANONYMOUS`. When set to `NONE`, no filter is applied.
search	stringfield:value Example: search=firstName:John Filter the results by parameter values. `field` is the name of a field in the Profile. If you enter a simple string (not a `field:value` pattern), the search will take the following parameters into account: email, first name, last name, UUID, custom parameters.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/crm/v1/segmentations/local/%7BUUID%7D/clients?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE&recognized=SOME_STRING_VALUE&search=firstName%3AJohn' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"customers": [{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}
],
"all": 0,
"limit": 0,
"offset": 0,
"matching": 0
}

Get Profiles from segmentation

Retrieve a list of Profiles from a segmentation. Unlike ad-hoc segmentations, these are available from the Analytics > Segmentations menu.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_FROM_SEGMENTATION_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

path Parameters

UUID

required

string <uuid>

UUID of the segmentation

query Parameters

limit	integer <int32> Default: 25 The maximum number of items to retrieve. This can be used for pagination.
offset	integer <int32> Default: 0 The ID of the first item to retrieve. This is used for pagination. For example, to retrieve items starting at number 11, set offset to 10.
recognized	string Default: "NONE" Enum: "RECOGNIZED" "true" "ANONYMOUS" "false" "NONE" Filter the results by Profile's anonymity status. `true` is the same as `RECOGNIZED`. `false` is the same as `ANONYMOUS`. When set to `NONE`, no filter is applied.
search	stringfield:value Example: search=firstName:John Filter the results by parameter values. `field` is the name of a field in the Profile. If you enter a simple string (not a `field:value` pattern), the search will take the following parameters into account: email, first name, last name, UUID, custom parameters.
sortBy	stringfield:orderType Choose a parameter to sort the results. `field` is the name of a field in the Profile. `orderType` can be `ASC` or `DESC`.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/crm/v1/segmentations/%7BUUID%7D/clients?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE&recognized=SOME_STRING_VALUE&search=firstName%3AJohn&sortBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"customers": [{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}
],
"all": 0,
"limit": 0,
"offset": 0,
"matching": 0
}

Create local segmentation

Create a new local segmentation. Local segmentations are set up ad-hoc when you're using filters on the list of Profiles in CRM.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_FROM_LOCAL_SEGMENTATION_CLIENT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

query Parameters

recognized

string

Default: "NONE"

Enum: "RECOGNIZED" "true" "ANONYMOUS" "false" "NONE"

Filter the results by Profile's anonymity status. true is the same as RECOGNIZED. false is the same as ANONYMOUS. When set to NONE, no filter is applied.

Request Body schema: application/json

The body of this request contains a request to the analytics service.

object

Responses

Request samples

Content type

application/json

{ }

Response samples

200

Content type

application/json

"e1ba2639-bab9-4951-a21b-1488b085b7b6"

Create materialization Deprecated

A segmentation's results change in real-time due to constant Profile activity.

A materialization allows you to take a "snapshot" of the segmentation that can be used for further work. The materialization includes the Profiles that the segmentation returned at the time this request was received.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_FROM_MATERIALIZATION_CLIENT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

Request Body schema: application/json

segment

string

UUID of the segmentation

Responses

Request samples

Content type

application/json

{"segment": "string"
}

Response samples

200

Content type

application/json

{"materializationId": 0,
"expiration": "2019-08-24T14:15:22Z",
"count": 0
}

List Profiles from a materialization Deprecated

You can retrieve the list of Profiles from a materialization.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_LIST_FROM_MATERIALIZATION_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_LIST

Authorizations:

JWT

path Parameters

materializationId

required

integer

ID of the materialization

query Parameters

limit	integer <int32> Default: 25 The maximum number of items to retrieve. This can be used for pagination.
offset	integer <int32> Default: 0 The ID of the first item to retrieve. This is used for pagination. For example, to retrieve items starting at number 11, set offset to 10.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/crm/v1/clients/list/%7BmaterializationId%7D?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"materializationId": 0,
"customers": [{"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"anonymous_type": "UUID",
"email": "string",
"firstname": "string",
"lastName": "string",
"custom_identify": "string",
"company": "string",
"phone": "string",
"address": "string",
"birthdate": "string",
"city": "string",
"zipCode": "string",
"province": "string",
"country_id": "string",
"countryCode": "PL",
"avatarUrl": "string",
"sex": "FEMALE",
"last_activity_date": "2019-08-24",
"created": "2019-08-24",
"updated": "2019-08-24",
"deletedAt": "2019-08-24",
"tags": ["string"
]
}
],
"offset": 0,
"limit": 0
}

Get Profile's last activity date

Retrieve the date of a Profile's last activity.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: CRM_DETAILS_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer

Profile ID

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/crm/v1/clients/%7BclientId%7D/last-activity 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"last_activity_date": "2019-08-24T14:15:22Z"
}

Get all Profile notes

Retrieve all notes associated with a single profile.

API consumer who can use this method: Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: NOTES_SERVICE_ALL_NOTES_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_NOTES

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Profile ID

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/notes-service/by-id/%7BclientId%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"body": "<h1>NOTE 1</h1>\\n<p>Some text</p>\\n<ul>\\n<li>1</li>\\n<li>2</li>\\n<li>3</li>\\n</ul>\\n<blockquote>Lorem ipsum in quote</blockquote>\\n<p><strong>Lorem ipsum in bold</strong></p>\\n",
"created": 1564646611.556,
"createdBy": "example@example.com",
"id": "69b0e925-086a-4964-b8dc-4c9e58213cf5",
"subject": "Note 1",
"updated": 1564646618.556,
"updatedBy": "example@example.com",
"userId": 11405
}
]

Create a note

Create a new note in the profile

API consumer who can use this method: Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: NOTES_SERVICE_NOTE_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_NOTES

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Profile ID

Request Body schema: application/json

subject	string The title of the note
body	string Text of the note

Responses

Request samples

Content type

application/json

{"subject": "Note 1",
"body": "<h1>NOTE 1</h1>\\n<p>Some text</p>\\n<ul>\\n<li>1</li>\\n<li>2</li>\\n<li>3</li>\\n</ul>\\n<blockquote>Lorem ipsum in quote</blockquote>\\n<p><strong>Lorem ipsum in bold</strong></p>\\n"
}

Response samples

200

Content type

application/json

{"body": "<h1>NOTE 1</h1>\\n<p>Some text</p>\\n<ul>\\n<li>1</li>\\n<li>2</li>\\n<li>3</li>\\n</ul>\\n<blockquote>Lorem ipsum in quote</blockquote>\\n<p><strong>Lorem ipsum in bold</strong></p>\\n",
"created": 1564646611.556,
"createdBy": "example@example.com",
"id": "69b0e925-086a-4964-b8dc-4c9e58213cf5",
"subject": "Note 1",
"updated": 1564646618.556,
"updatedBy": "example@example.com",
"userId": 11405
}

Get note

Retrieve a single note

API consumer who can use this method: Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: NOTES_SERVICE_NOTE_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_NOTES

Authorizations:

JWT

path Parameters

clientId required	integer <int64> Profile ID
noteId required	string Note UUID

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/notes-service/by-id/%7BclientId%7D/%7BnoteId%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"body": "<h1>NOTE 1</h1>\\n<p>Some text</p>\\n<ul>\\n<li>1</li>\\n<li>2</li>\\n<li>3</li>\\n</ul>\\n<blockquote>Lorem ipsum in quote</blockquote>\\n<p><strong>Lorem ipsum in bold</strong></p>\\n",
"created": 1564646611.556,
"createdBy": "example@example.com",
"id": "69b0e925-086a-4964-b8dc-4c9e58213cf5",
"subject": "Note 1",
"updated": 1564646618.556,
"updatedBy": "example@example.com",
"userId": 11405
}

Update note

You can update an existing note.

API consumer who can use this method: Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: NOTES_SERVICE_NOTE_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_NOTES

Authorizations:

JWT

path Parameters

clientId required	integer <int64> Profile ID
noteId required	string Note UUID

Request Body schema: application/json

subject	string The title of the note
body	string Text of the note

Responses

Request samples

Content type

application/json

{"subject": "Note 1",
"body": "<h1>NOTE 1</h1>\\n<p>Some text</p>\\n<ul>\\n<li>1</li>\\n<li>2</li>\\n<li>3</li>\\n</ul>\\n<blockquote>Lorem ipsum in quote</blockquote>\\n<p><strong>Lorem ipsum in bold</strong></p>\\n"
}

Response samples

200

Content type

application/json

{"body": "<h1>NOTE 1</h1>\\n<p>Some text</p>\\n<ul>\\n<li>1</li>\\n<li>2</li>\\n<li>3</li>\\n</ul>\\n<blockquote>Lorem ipsum in quote</blockquote>\\n<p><strong>Lorem ipsum in bold</strong></p>\\n",
"created": 1564646611.556,
"createdBy": "example@example.com",
"id": "69b0e925-086a-4964-b8dc-4c9e58213cf5",
"subject": "Note 1",
"updated": 1564646618.556,
"updatedBy": "example@example.com",
"userId": 11405
}

Delete note

You can delete a note. This operation is irreversible.

API consumer who can use this method: Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: NOTES_SERVICE_NOTE_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_NOTES

Authorizations:

JWT

path Parameters

clientId required	integer <int64> Profile ID
noteId required	string Note UUID

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/notes-service/by-id/%7BclientId%7D/%7BnoteId%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Log out a Profile

Log out a Profile when authenticated as a Synerise User or a Workspace.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_LOGOUT_CLIENT_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: SETTINGS_CUSTOMERS_IAM

path Parameters

clientID

required

string

Example: 434428563

The ID of the Profile

Request Body schema: application/json

action

string

Enum: "LOGOUT" "LOGOUT_WITH_SESSION_CLEARING"

Responses

Request samples

Content type

application/json

{"action": "LOGOUT"
}

Response samples

401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Profile account management

As a Profile, manage your own account data

Get Profile's own data

A Profile can retrieve its details from the database.

API consumers who can use this method: Profile (formerly client), null
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PERSONAL_INFORMATION_CLIENT_READ

Authorizations:

JWT

header Parameters

Api-Version required	string Value: "4.4"
Content-Type required	string Value: "application/json"

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/v4/my-account/personal-information 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

200
401
403
415

Content type

application/json

{"clientId": 0,
"email": "string",
"phone": "+48111222333",
"customId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"firstName": "string",
"lastName": "string",
"displayName": "string",
"company": "string",
"address": "string",
"city": "string",
"province": "string",
"zipCode": "string",
"countryCode": "PL",
"birthDate": "1987-10-24",
"sex": "FEMALE",
"avatarUrl": "string",
"anonymous": false,
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
],
"previousClients": [0
],
"lastActivityDate": "2019-03-19T14:05:39Z"
}

Update Profile's own data

A Profile can update its own details.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PERSONAL_INFORMATION_CLIENT_UPDATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

address	string Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
avatarUrl	string or null URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
birthDate	string Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
city	string Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
company	string Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
countryCode	string Code of profile's country of residence in accordance with the ISO 3166 format
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
displayName	string Currently unused
email	string The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+)*)\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication.
firstName	string Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
lastName	string Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
phone	string Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
province	string Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
sex	string Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER" Profile's sex
zipCode	string Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"address": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"avatarUrl": "string",
"birthDate": "1987-10-24",
"city": "string",
"company": "string",
"countryCode": "PL",
"customId": "string",
"displayName": "string",
"email": "string",
"firstName": "string",
"lastName": "string",
"phone": "+48111222333",
"province": "string",
"sex": "FEMALE",
"zipCode": "string"
}

Response samples

400
401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-29T13:08:16.235Z",
"path": "/my-account/personal-information",
"message": "Some fields did not pass validation",
"errors": [{"code": 120,
"field": "avatarUrl",
"message": "120",
"rejectedValue": "548869"
}
]
}

Request profile phone number change

A Profile can request a phone number update. The confirmation code is sent in a text message.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PERSONAL_PHONE_CLIENT_UPDATE

Authorizations:

JWT

header Parameters

Accept required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Request Body schema: application/json

phone

required

string

Current phone number of the profile.

Must match the pattern (ECMA flavor): /(^\+[0-9 \-()/]{6,19}$)|(^[0-9 \-()/]{6,20}$)/

Responses

Request samples

Content type

application/json

{"phone": "+48111222333"
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Confirm profile phone number change

Use a code to confirm the phone number change and provide the new number.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PERSONAL_PHONE_CLIENT_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

phone required	string New phone number Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/`
confirmationCode required	string Confirmation code received by text message
deviceId	string Unique Android or iOS device ID
smsAgreement	boolean Permission to receive marketing information by SMS

Responses

Request samples

Content type

application/json

{"phone": "+48111222333",
"confirmationCode": "73AC1",
"deviceId": "string",
"smsAgreement": true
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Request Profile password reset

Allows a Profile to send a password reset request. A reset link is sent to the specified email address. To confirm the request, use the Confirm a Profile's password reset endpoint.

API consumers who can use this method: Anonymous profile (formerly client), Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_PASSWORD_RESET_CLIENT_CREATE

Authorizations:

JWT

Request Body schema: application/json

email

required

string

Email address where the password reset link will be sent

Responses

Request samples

Content type

application/json

{"email": "testDoc@example.com"
}

Response samples

401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Confirm Profile password reset

Confirm a password reset using the token obtained from the Request Profile password reset endpoint.

API consumers who can use this method: Anonymous profile (formerly client), Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_PASSWORD_RESET_CLIENT_CREATE

Authorizations:

JWT

Request Body schema: application/json

password required	string New password
token required	string Token received by email

Responses

Request samples

Content type

application/json

{"password": "testPass1!",
"token": "token_from_pass_reset_req"
}

Change Profile password

A Profile can update the password to its account.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_CHANGE_PASSWORD_CLIENT_UPDATE

Authorizations:

JWT

Request Body schema: application/json

oldPassword	string Current password
password	string New password
deviceId	string Unique Android or iOS device ID

Responses

Request samples

Content type

application/json

{"oldPassword": "test1.1234",
"password": "Test.1234",
"deviceId": "optional"
}

Response samples

400

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2018-08-01T19:46:52.178Z",
"message": "Password must have at least 6 characters and must contain at least one digit, one letter and one special character",
"path": "/my-account/change-password"
}

Delete account

A Profile can delete its own account. Its CRM history shows an client.deleteAccount event. All marketing agreements are cancelled. The profile is signed out on all devices and cannot sign in again.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_CLIENT_DELETE

Authorizations:

JWT

Request Body schema: application/json

password required	string Profile password. Only applicable if the Profile is not authenticated by an external identity provider.
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
externalToken	string External authorization token. Only applicable if the Profile is authenticated by an external identity provider.
customId	string Custom ID of the Profile, if applicable
identityProvider required	string Enum: "FACEBOOK" "OAUTH" "APPLE" "SYNERISE" Authorization provider
deviceId	string Unique Android or iOS device ID

Responses

Request samples

Content type

application/json

{"password": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"externalToken": "string",
"customId": "string",
"identityProvider": "FACEBOOK",
"deviceId": "string"
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Request Profile email change

A Profile can request an email change for its own account. A confirmation token is sent to the new email by and must be applied by clicking the link in the message or using the Confirm Profile email change endpoint.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_EMAIL_CHANGE_CLIENT_UPDATE

Request Body schema: application/json

email required	string New email address
externalToken	string External authorization token. Only applicable if the Profile is authenticated by an external identity provider.
password	string Profile password. Only applicable if the Profile is not authenticated by an external identity provider.
uuid required	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique Android or iOS device ID
customId	string Custom ID of the Profile, if applicable

Responses

Request samples

Content type

application/json

{"email": "string",
"externalToken": "string",
"password": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"deviceId": "string",
"customId": "string"
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Log out a Profile

Log out a Profile when authenticated as that Profile.

API consumers who can use this method: Profile (formerly client), null
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_LOGOUT_CLIENT_CREATE

Request Body schema: application/json

action

string

Enum: "LOGOUT" "LOGOUT_WITH_SESSION_CLEARING"

Responses

Request samples

Content type

application/json

{"action": "LOGOUT"
}

Response samples

401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Confirm Profile email change

The Profile can confirm the email change by providing the token that they received by email as a result of the Request a Profile email change call.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_CHANGE_EMAIL_CLIENT_UPDATE

Authorizations:

JWT

Request Body schema: application/json

token	string <uuid> Token received by email
newsletterAgreement	boolean Permission to receive email newsletters

Responses

Request samples

Content type

application/json

{"token": "token_from_email_change_mail",
"newsletterAgreement": true
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Change Facebook Profile email

Change the email address of a Profile registered by Facebook

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_EMAIL_CHANGE_CLIENT_UPDATE

Authorizations:

JWT

Request Body schema: application/json

email	string New email address
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique Android or iOS device ID

Responses

Request samples

Content type

application/json

{"email": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"deviceId": "string"
}

Response samples

401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Delete Client Account (OAuth) Deprecated

This endpoint is deprecated. Use this one.

A Client can delete their own account.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_OAUTH_CLIENT_DELETE

Authorizations:

JWT

Request Body schema: application/json

accessToken	string OAuth access token
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique Android or iOS device ID
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`

Responses

Request samples

Content type

application/json

{"accessToken": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"deviceId": "string",
"customId": "string"
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Delete Profile account (Sign in with Apple) Deprecated

This endpoint is deprecated. Use this one.

A Profile can delete its own account.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_APPLE_CLIENT_DELETE

Authorizations:

JWT

Request Body schema: application/json

accessToken	string Apple access token
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique Android or iOS device ID
customId	string A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`

Responses

Request samples

Content type

application/json

{"accessToken": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"deviceId": "string",
"customId": "string"
}

Response samples

401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Delete Facebook Profile Account Deprecated

This endpoint is deprecated. Use this one.

A Profile can delete its own account.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_FACEBOOK_CLIENT_DELETE

Authorizations:

JWT

Request Body schema: application/json

facebookToken	string Facebook authentication token
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique Android or iOS device ID

Responses

Request samples

Content type

application/json

{"facebookToken": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"deviceId": "string"
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Delete account Deprecated

This endpoint is deprecated. Use this one.

A Profile can delete its own account.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_CLIENT_DELETE

Authorizations:

JWT

Request Body schema: application/json

password	string Profile password
uuid	string Profile UUID
deviceId	string Unique Android or iOS device ID

Responses

Request samples

Content type

application/json

{"password": "string",
"uuid": "string",
"deviceId": "string"
}

Response samples

400
401
403

Content type

application/json

{"error": "string",
"message": "string",
"errors": [{"code": 0,
"field": "string",
"message": "string",
"rejectedValue": "string"
}
],
"status": 0,
"timestamp": "string",
"path": "string",
"traceId": "string"
}

Request Profile email change Deprecated

This endpoint is deprecated. Use this one.

A Profile can request an email change for its account. A confirmation token is sent by and must be applied using the Confirm Profile email change endpoint.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_CHANGE_EMAIL_CLIENT_UPDATE

Authorizations:

JWT

Request Body schema: application/json

email	string New email address
password	string Profile password
uuid	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique Android or iOS device ID

Responses

Request samples

Content type

application/json

{"email": "newEmail",
"password": "my_password",
"uuid": "my_uuid",
"deviceId": "optional"
}

Profile devices

Link devices to Profiles

Link a device by profile ID

Assign a device to a profile ID. A profile may have many devices assigned.

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_DEVICE_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Example: 434428563

The ID of the profile

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

deviceId required	string Unique Android or iOS device ID
registrationId required	string Registration ID for Firebase Cloud Messaging
type required	string Enum: "android" "ios" "windows" Device type
bluetoothAddress	string Bluetooth MAC address of the device
macAddress	string MAC address of the network adapter
manufacturer	string Manufacturer of the device
model	string Model of the device
osVersion	string Operating system of the device
product	string Additional information about the OS on the device
screenHeight	integer <int32> Screen height in pixels
screenWidth	integer <int32> Screen width in pixels
publicKey	string Public key used to encrypt push messages

Responses

Request samples

Content type

application/json

{"deviceId": "string",
"registrationId": "string",
"type": "android",
"bluetoothAddress": "string",
"macAddress": "string",
"manufacturer": "string",
"model": "string",
"osVersion": "string",
"product": "a51ul_htc_europe",
"screenHeight": 0,
"screenWidth": 0,
"publicKey": "string"
}

Response samples

400
401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-29T12:34:02.222Z",
"path": "/clients/1245757/linked-devices",
"message": "Some fields did not pass validation",
"errors": [{"code": 12301,
"field": "deviceId",
"message": "12301"
}
]
}

Link a device by other parameters

Assign a device to a profile UUID. A profile may have many devices assigned.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BY_IDENTIFY_DEVICE_CLIENT_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_INFO

Authorizations:

JWT

path Parameters

identifierType required	string Enum: "by-customId" "by-uuid" The profile identifier to use for the request
identifierValue required	string The value of the selected identifier

header Parameters

Accept required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Request Body schema: application/json

deviceId required	string Unique Android or iOS device ID
registrationId required	string Registration ID for Firebase Cloud Messaging
type required	string Enum: "android" "ios" "windows" Device type
bluetoothAddress	string Bluetooth MAC address of the device
macAddress	string MAC address of the network adapter
manufacturer	string Manufacturer of the device
model	string Model of the device
osVersion	string Operating system of the device
product	string Additional information about the OS on the device
screenHeight	integer <int32> Screen height in pixels
screenWidth	integer <int32> Screen width in pixels
publicKey	string Public key used to encrypt push messages

Responses

Request samples

Content type

application/json

{"deviceId": "string",
"registrationId": "string",
"type": "android",
"bluetoothAddress": "string",
"macAddress": "string",
"manufacturer": "string",
"model": "string",
"osVersion": "string",
"product": "a51ul_htc_europe",
"screenHeight": 0,
"screenWidth": 0,
"publicKey": "string"
}

Response samples

400
401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-29T12:34:02.222Z",
"path": "/clients/by-uuid/779465fc-a0c5-41e5-9be2-51c00b2588b4/linked-devices",
"message": "Some fields did not pass validation",
"errors": [{"code": 12301,
"field": "deviceId",
"message": "12301"
}
]
}

Link a device to currently logged in profile

Assign a device to the profile that is currently logged in. A Profile may have many devices assigned.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PERSONAL_DEVICE_CLIENT_UPDATE

Authorizations:

JWT

header Parameters

Accept required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Request Body schema: application/json

deviceId required	string Unique Android or iOS device ID
registrationId required	string Registration ID for Firebase Cloud Messaging
type required	string Enum: "android" "ios" "windows" Device type
bluetoothAddress	string Bluetooth MAC address of the device
macAddress	string MAC address of the network adapter
manufacturer	string Manufacturer of the device
model	string Model of the device
osVersion	string Operating system of the device
product	string Additional information about the OS on the device
screenHeight	integer <int32> Screen height in pixels
screenWidth	integer <int32> Screen width in pixels
publicKey	string Public key used to encrypt push messages

Responses

Request samples

Content type

application/json

{"deviceId": "string",
"registrationId": "string",
"type": "android",
"bluetoothAddress": "string",
"macAddress": "string",
"manufacturer": "string",
"model": "string",
"osVersion": "string",
"product": "a51ul_htc_europe",
"screenHeight": 0,
"screenWidth": 0,
"publicKey": "string"
}

Response samples

401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-29T13:08:16.235Z",
"path": "/exampleEndpoint",
"message": "Some fields did not pass validation",
"errors": [{"code": 120,
"field": "exampleField",
"message": "120",
"rejectedValue": "exampleValue"
}
]
}

Profile tags

Tags that can be attributed to Profiles

Get all tags

Retrieve all tags that can be assigned to profiles.

This endpoint is available from version 4.1.0

API consumers who can use this method: Synerise User, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_TAGS_CLIENT_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_TAGS

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/v4/clients/tags 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
401
403

Content type

application/json

[{"id": 645,
"name": "nice tag",
"color": "#0768ff"
}
]

Create a tag

Create a new tag that can be assigned to profiles. If you try to create a tag that already exists, the response is the existing tag.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_TAGS_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_TAGS

Authorizations:

JWT

Request Body schema: application/json

name required	string Name of the tag
color	string Display color of the tag; hexadecimal value

Responses

Request samples

Content type

application/json

{"name": "nice tag",
"color": "#0768ff"
}

Response samples

200
400
401
403
415

Content type

application/json

{"businessProfileId": 100005,
"id": 645,
"name": "nice tag",
"color": "#0768ff"
}

Update a tag

Update a tag. This method currently only allows modifying the color field.

If the tag has been already deleted, the response is a 404 error.

Important: This method doesn't update global tags (not related to any workspace). If you try to update a global tag, the response is a 404 error.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_TAGS_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_TAGS

Authorizations:

JWT

path Parameters

tagID

required

integer

Example: 645

ID of the tag

Request Body schema: application/json

color

string

Display color of the tag; hexadecimal value

Responses

Request samples

Content type

application/json

{"color": "#0768ff"
}

Response samples

Content type

application/json

{"businessProfileId": 100005,
"id": 645,
"name": "nice tag",
"color": "#0768ff"
}

Remove a tag

Remove a tag definition from the workspace.

If the tag has been already deleted, the response is a 404 error.

Important: This method does not remove global tag (not related to any workspace). In this case, the response is a 404 error.

Note: After removing a tag definition, the tag is still cached for a while. In that time, it is still possible for a while to remove or add this tag in profiles.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_TAGS_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_TAGS

Authorizations:

JWT

path Parameters

tagID

required

integer

Example: 645

ID of the tag

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/v4/tags/%7BtagID%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

400
401
403
404
415

Content type

application/json

{"error": "string",
"status": 0,
"timestamp": "string",
"path": "string",
"message": "string",
"errors": [{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
]
}

Get profile tags

Retrieve a list of tags assigned to a profile.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_TAGS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_TAGS

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Example: 434428563

The ID of the profile

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/v4/clients/%7BclientId%7D/tags 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
401
403

Content type

application/json

[{"id": 645,
"name": "nice tag",
"color": "#0768ff"
}
]

Assign tag to profile

Assign a tag to a profile.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_ASSIGN_TAGS_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_TAGS

path Parameters

clientId required	integer <int64> Example: 434428563 The ID of the profile
tagID required	integer Example: 645 ID of the tag

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/v4/clients/%7BclientId%7D/tags/%7BtagID%7D

Response samples

Content type

application/json

{"clientId": 0,
"id": 73,
"tagId": 645
}

Remove tag from profile

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_ASSIGN_TAGS_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_TAGS

path Parameters

clientId required	integer <int64> Example: 434428563 The ID of the profile
tagID required	integer Example: 645 ID of the tag

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/v4/clients/%7BclientId%7D/tags/%7BtagID%7D

Response samples

400
401
403
404

Content type

application/json

{"error": "string",
"status": 0,
"timestamp": "string",
"path": "string",
"message": "string",
"errors": [{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
]
}

Events

Record Profile actions and retrieve them for use within your applications

Create a transaction

Create a transaction record in the database.

For each transaction, a transaction.charge event is generated automatically. In addition, each item in the products array produces a product.buy event.

All monetary values must use the same currency and be greater than or equal to zero. discountAmount must be greater than zero or omitted.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_TRANSACTION_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

required	object You must provide at least one of those profile identifiers.
	object or null How much the total cost decreased
	object Any custom parameters
orderId required	string ID of the transaction. If you want to be able to overwrite this transaction in the future, you use `eventSalt`. If you send a transaction with the same `orderId` multiple times, the system generates multiple transaction events.
required	object Payment details
required	Array of objects[ items ] A list of items in the transaction. Each item creates a `product.buy` event. The UUID of that event is generated from a combination of: the UUID of the `transaction.charge` event created by the transaction the position of the item in this array. This has an effect on updating transaction events. This means that when you update a transaction (a transaction can only be updated if it has an `eventSalt` and the same timestamp as the original), you must keep the original order of items in the array. Otherwise, you may accidentally overwrite a `product.buy` event with another item's event. The system does NOT recognize the item by SKU in this case. Example: You create a transaction with items A, B, and C (in that order). You update the transaction and the items are now A, B, D, and C (in that order). Because item D took the position of C in the event, it has the same UUID as C had earlier. The event of D overwrites the event of C, and C is generated as a new event. Additionally, because events can't be deleted from the database, cancelled items remain as events in a Profile's history. You can use a custom free-form property to tag items as cancelled. This way, you can keep cancelled items in `products` when updating a transaction without breaking the order of items. You can also use the property to filter cancelled items out in Analytics.
recordedAt	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
required	object Transaction revenue (amount after taxation). This field is not calculated automatically by the backend, you must provide the value by summing up the results of `finalUnitPrice * quantity` from all items in the `products` array.
required	object If you want to display the price before taxation, use this object. If you only want to display the price after taxation, set the values to the same as in `revenue`.
source required	string Enum: "WEB_DESKTOP" "WEB_MOBILE" "MOBILE_APP" "POS" "MOBILE" "DESKTOP" Source of the event.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.

Responses

Request samples

Content type

application/json

{"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"discountAmount": {"amount": 0,
"currency": "USD"
},
"metadata": { },
"orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
"paymentInfo": {"method": "CASH"
},
"products": [{"finalUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"name": "Soft drink",
"sku": "189784563455",
"categories": ["string"
],
"image": "string",
"url": "string",
"netUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"tax": 0,
"quantity": 2.5,
"regularPrice": {"amount": 3.25,
"currency": "USD"
},
"discountPrice": {"amount": 15.5,
"currency": "USD"
},
"discountPercent": 0,
"property1": null,
"property2": null
}
],
"recordedAt": "2019-02-07T09:53:56.999+00:00",
"revenue": {"amount": 64.25,
"currency": "USD"
},
"value": {"amount": 112.25,
"currency": "USD"
},
"source": "MOBILE",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00"
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2020-10-28T12:14:45.364+00:00",
"status": 400,
"error": "Bad Request",
"message": "JSON parse error: Missing property: 'currency'; nested exception is com.fasterxml.jackson.databind.JsonMappingException: Missing property: 'currency'\n at [Source: (PushbackInputStream); line: 13, column: 14] (through reference chain: com.synerise.api.endpoint.transactions.domain.model.IdentifiedTransactionData[\"products\"]->java.util.ArrayList[0]->com.synerise.api.endpoint.transactions.domain.model.ProductData[\"finalUnitPrice\"])",
"path": "/transactions"
}

Batch add or update transactions

Enqueue a number of add/update operations in the Synerise application database.

For each transaction, a transaction.charge event is generated automatically. In addition, each item in the products array produces a product.buy event.

If you don't have some information about a transaction, don't insert a null-value parameter - omit the parameter entirely. Sending a null value deletes an attribute (if it's a custom attribute) or sets it to null/default value (if the attribute is Synerise-native).

The body contains an array of objects to update. The objects are the same as in the Update transaction and Create transaction endpoints.

All monetary values must use the same currency and be greater than or equal to zero. discountAmount must be greater than zero or omitted.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BATCH_TRANSACTION_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

An array of transactions to post or update

Array

required	object You must provide at least one of those profile identifiers.
	object or null How much the total cost decreased
	object Any custom parameters
orderId required	string ID of the transaction. If you want to be able to overwrite this transaction in the future, you use `eventSalt`. If you send a transaction with the same `orderId` multiple times, the system generates multiple transaction events.
required	object Payment details
required	Array of objects[ items ] A list of items in the transaction. Each item creates a `product.buy` event. The UUID of that event is generated from a combination of: the UUID of the `transaction.charge` event created by the transaction the position of the item in this array. This has an effect on updating transaction events. This means that when you update a transaction (a transaction can only be updated if it has an `eventSalt` and the same timestamp as the original), you must keep the original order of items in the array. Otherwise, you may accidentally overwrite a `product.buy` event with another item's event. The system does NOT recognize the item by SKU in this case. Example: You create a transaction with items A, B, and C (in that order). You update the transaction and the items are now A, B, D, and C (in that order). Because item D took the position of C in the event, it has the same UUID as C had earlier. The event of D overwrites the event of C, and C is generated as a new event. Additionally, because events can't be deleted from the database, cancelled items remain as events in a Profile's history. You can use a custom free-form property to tag items as cancelled. This way, you can keep cancelled items in `products` when updating a transaction without breaking the order of items. You can also use the property to filter cancelled items out in Analytics.
recordedAt	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
required	object Transaction revenue (amount after taxation). This field is not calculated automatically by the backend, you must provide the value by summing up the results of `finalUnitPrice * quantity` from all items in the `products` array.
required	object If you want to display the price before taxation, use this object. If you only want to display the price after taxation, set the values to the same as in `revenue`.
source required	string Enum: "WEB_DESKTOP" "WEB_MOBILE" "MOBILE_APP" "POS" "MOBILE" "DESKTOP" Source of the event.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.

Responses

Request samples

Content type

application/json

[{"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"discountAmount": {"amount": 0,
"currency": "USD"
},
"metadata": { },
"orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
"paymentInfo": {"method": "CASH"
},
"products": [{"finalUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"name": "Soft drink",
"sku": "189784563455",
"categories": ["string"
],
"image": "string",
"url": "string",
"netUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"tax": 0,
"quantity": 2.5,
"regularPrice": {"amount": 3.25,
"currency": "USD"
},
"discountPrice": {"amount": 15.5,
"currency": "USD"
},
"discountPercent": 0,
"property1": null,
"property2": null
}
],
"recordedAt": "2019-02-07T09:53:56.999+00:00",
"revenue": {"amount": 64.25,
"currency": "USD"
},
"value": {"amount": 112.25,
"currency": "USD"
},
"source": "MOBILE",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00"
}
]

Response samples

400
401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2020-10-28T12:24:24.444Z",
"path": "/transactions",
"message": "Some fields did not pass validation",
"errors": [{"code": 14191,
"field": "client",
"message": "Client cannot have null value"
}
]
}

Get Profile events as Workspace Deprecated

This endpoint is deprecated. Use /activities-api/events/by/{identifierType} instead.

Retrieve a list of events saved in a Profile.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_LISTING_BY_CLIENT_EVENTS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_ACTIVITIES

Authorizations:

JWT

path Parameters

clientId

required

integer <int64>

Example: 434428563

The ID of the profile

query Parameters

time[from]	string <date-time> Start of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the results are returned starting with the oldest entry in the database.
time[to]	string <date-time> End of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the current time applies.
action	string Example: action=transaction.charge Filter events by action type. For example, to retrieve completed transactions, enter `transaction.charge`
limit	integer [ 1 .. 500 ] The number of events to retrieve

header Parameters

Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/v4/events/by-client/%7BclientId%7D?time%5Bfrom%5D=SOME_STRING_VALUE&time%5Bto%5D=SOME_STRING_VALUE&action=transaction.charge&limit=SOME_INTEGER_VALUE' 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

200
401
403

Content type

application/json

[{"time": "string",
"action": "client.updateData",
"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"params": {"eventCreateTime": 1669228766.789,
"ip": { },
"property1": null,
"property2": null
}
}
]

Get Profile's own events Deprecated

This endpoint is deprecated. Use /activities-api/events instead.

A Profile can retrieve a list of its own events saved in the database.

API consumer who can use this method: Profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_LISTING_CLIENT_OWN_EVENTS_READ

Authorizations:

JWT

query Parameters

time[from]	string <date-time> Start of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the results are returned starting with the oldest entry in the database.
time[to]	string <date-time> End of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the current time applies.
action	string Example: action=transaction.charge Filter events by action type. For example, to retrieve completed transactions, enter `transaction.charge`
limit	integer [ 1 .. 500 ] The number of events to retrieve

header Parameters

Content-Type required	string Value: "application/json"
Api-Version required	string Value: "4.4"

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/v4/events?time%5Bfrom%5D=SOME_STRING_VALUE&time%5Bto%5D=SOME_STRING_VALUE&action=transaction.charge&limit=SOME_INTEGER_VALUE' 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_' 
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

200
401
403
415
500

Content type

application/json

[{"time": "string",
"action": "client.updateData",
"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"params": {"eventCreateTime": 1669228766.789,
"ip": { },
"property1": null,
"property2": null
}
}
]

Application started

Send a 'client application started' event.

This endpoint is available from API version 4.1.2.

When you send an event to this endpoint, the action field is set to client.applicationStarted by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_APPLICATION_STARTED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
required	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"applicationName": "string",
"version": "string"
}
}

Response samples

400
401
403
415
500

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Profile account registered

Send a 'profile account registered' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to client.register by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_REGISTERED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Profile logged in

Send a 'profile logged in' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to client.login by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_LOGGED_IN_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Profile logged out

Send a 'profile logged out' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to client.logout by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_LOGGED_OUT_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Item added to cart

Send an 'item added to cart' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to product.addToCart by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_ADDED_TO_CART_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
required	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile who generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"sku": "189784563455",
"name": "Soft drink",
"category": "Beverages",
"categories": ["string"
],
"offline": true,
"source": "MOBILE",
"regularUnitPrice": {"amount": 0,
"currency": "USD"
},
"discountedUnitPrice": {"amount": 0,
"currency": "USD"
},
"finalUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"ItemUrlAddress": "string",
"producer": "string",
"quantity": 0
}
}

Response samples

400
401
403
415

Content type

application/json

{"error": "Bad Request",
"status": 400,
"timestamp": "2018-06-07T09:55:20.563Z",
"message": "Some fields did not pass validation",
"path": "/events/added-to-cart",
"errors": [{"path": "label",
"message": "cannot be empty",
"rejectedValue": ""
},
{"path": "label",
"message": "length must be between 1 and 64",
"rejectedValue": ""
}
]
}

Item removed from cart

Send an 'item removed from cart' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to product.removeFromCart by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_REMOVED_FROM_CART_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
required	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile who generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"sku": "189784563455",
"name": "Soft drink",
"category": "Beverages",
"categories": ["string"
],
"offline": true,
"source": "MOBILE",
"regularUnitPrice": {"amount": 0,
"currency": "USD"
},
"discountedUnitPrice": {"amount": 0,
"currency": "USD"
},
"finalUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"ItemUrlAddress": "string",
"producer": "string",
"quantity": 0
}
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Product added to favorites

Send an 'item added to favorites' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to product.addToFavorite by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_ADDED_TO_FAVORITES_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Item viewed

Send an 'item viewed' event.

When you send an event to this endpoint, the action field is set to product.view by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PRODUCT_VIEW_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"productId": "189784563455",
"name": "Soft drink",
"fromRecommendation": true,
"source": "MOBILE",
"category": "Beverages",
"url": "string",
"campaignHash": "21e0d4b0-bd4e-497b-817b-4fr660284918"
}
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Profile assigned to company

Send a 'profile assigned to company' event.

When you send an event to this endpoint, the action field is set to client.assignToCompany by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User, Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_ASSIGNED_TO_COMPANY_EVENTS_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_ACTIVITIES

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
required	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"companyId": 0
}
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Profile logged location

Send an event when a profile submits its location.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to client.location by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_APPEARED_IN_LOCATION_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"lat": 50.021102,
"lon": 19.886218
}
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Push notification received

Record a 'push notification was received' event. It is used for push message interaction tracking.

This endpoint is available from API version 4.1.2.

When you send an event to this endpoint, the action field is set to push.receiveInBackground by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PUSH_RECIVED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Push notification viewed

Record a 'push notification was viewed' event. It is used for push message interaction tracking.

When you send an event to this endpoint, the action field is set to push.view by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PUSH_VIEWED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Push notification clicked

Send a 'Push notification was clicked' event. It's used for push message interaction tracking.

When you send an event to this endpoint, the action field is set to push.click by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PUSH_CLICKED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Push notifications cancelled

Send a 'push notifications cancelled' event. It's used for push message interaction tracking.

When you send an event to this endpoint, the action field is set to push.cancel by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_PUSH_CANCELLED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Transaction cancelled

Send a 'transaction cancelled' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to transaction.cancel by the backend.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_CANCELLED_TRANSACTION_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
"orderStatus": "string",
"discountAmount": {"amount": 0,
"currency": "USD"
},
"discountPercent": 0,
"discountCode": "string",
"value": {"amount": 112.25,
"currency": "USD"
},
"revenue": {"amount": 64.25,
"currency": "USD"
},
"products": [{"finalUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"name": "Soft drink",
"sku": "189784563455",
"categories": ["string"
],
"image": "string",
"url": "string",
"netUnitPrice": {"amount": 3.25,
"currency": "USD"
},
"tax": 0,
"quantity": 2.5,
"regularPrice": {"amount": 3.25,
"currency": "USD"
},
"discountPrice": {"amount": 15.5,
"currency": "USD"
},
"discountPercent": 0,
"property1": null,
"property2": null
}
],
"source": "MOBILE",
"paymentInfo": {"method": "CASH"
}
}
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Timer hit

Send a 'timer' event.

Timers are used for analytics. For example, if you send a event when a profiles starts doing something and another one when they finish, you can collect data about average activity time.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to client.hitTimer by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_HIT_TIMER_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Search requested

Send a 'search requested' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to client.search by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_SEARCHED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Content shared

Send a 'content shared' event.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to client.shared by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_SHARED_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Recommendation viewed Deprecated

This endpoint is deprecated. Use the AI Events endpoints instead.

Send a 'recommendation was viewed' event.

When you send an event to this endpoint, the action field is set to recommendation.view by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client), Web SDK tracker, AI API key (legacy)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_RECOMENDATION_SEEN_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile who generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"productId": "189784563455",
"name": "Soft drink",
"source": "MOBILE",
"campaignHash": "21e0d4b0-bd4e-497b-817b-4fr660284918",
"url": "string",
"category": "Beverages"
}
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Recommendation clicked Deprecated

Send a 'recommendation clicked' event. This endpoint is deprecated. Use the AI Events endpoints instead.

When you send an event to this endpoint, the action field is set to recommendation.click by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client), Web SDK tracker, AI API key (legacy)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_RECOMMENDATION_CLICK_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile who generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": {"productId": "189784563455",
"name": "Soft drink",
"source": "MOBILE",
"campaignHash": "21e0d4b0-bd4e-497b-817b-4fr660284918",
"url": "string",
"category": "Beverages"
}
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Mobile app screen visited

Send a 'screen in a mobile app was visited' event. This can be used for mobile screen usage tracking.

If you don't have a value for a field, omit that field. Do not send null values.

When you send an event to this endpoint, the action field is set to screen.view by the backend.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_VISITED_SCREEN_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Custom event

Send a custom event.

WARNING: This endpoint doesn't create product.buy events from transaction.charge events! Use Create a transaction or Batch add or update transactions instead.

If you don't have a value for a field, omit that field. Do not send null values.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_CUSTOM_EVENTS_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CLIENT_ACTIVITIES

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
action required	string For custom events, enter your own action name. For pre-defined events, omit this field. The action name can be up to 32 characters long and must match the following regular expression (ECMA flavor): `^[a-zA-Z0-9\.\-_]+$`
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"action": "context.action",
"params": { }
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Batch send events

Send a batch of events as an array of objects. You can send up to a 1000 events and the size of the request can't be more than 1 MB.

WARNING: This endpoint doesn't create product.buy events from transaction.charge events! Use Create a transaction or Batch add or update transactions instead.

If you don't have a value for a field, omit that field. Do not send null values.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_BATCH_EVENTS_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

IMPORTANT: In a request, all events must use the same type of profile identifier. For example, if you want to send some events identified by email and others by customId, you must send them in separate batches.

Array (<= 1000 items)

Any of

label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.
type required	string The type of event. If custom event, use `custom`. If other type, use the value that corresponds to the single event's endpoint.(for example, "content shared" events, which use the `/v4/events/shared` endpoint when sent as single events, have the type set to `shared`).
action required	string For custom events, enter your own action name. For pre-defined events, omit this field. The action name can be up to 32 characters long and must match the following regular expression (ECMA flavor): `^[a-zA-Z0-9\.\-_]+$`
	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. If you want to send a date/time param for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the params that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile which generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`

Responses

Request samples

Content type

application/json

[{"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
"type": "string",
"action": "context.action",
"params": { }
}
]

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Get server time

Get current server time, needed to send events with a correct timestamp.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client)
This method does not require a Synerise authorization token.

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/v4/server/time 
  --header 'Api-Version: SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
400
401
403

Content type

application/json

{"serverTime": "2019-08-24T14:15:22Z"
}

Recommendation viewed

A recommendation was displayed to a customer.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client), Web SDK tracker, AI API key (legacy)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_RECOMMENDATION_VIEW_EVENT_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

required	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile who generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`
label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.

Responses

Request samples

Content type

application/json

{"params": {"items": ["string"
],
"correlationId": "string",
"campaignId": "string"
},
"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00"
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}

Search result clicked

An item in a search result was clicked or tapped.

API consumers who can use this method: Workspace (formerly Business Profile), Profile (formerly client), Anonymous profile (formerly client), Web SDK tracker, AI API key (legacy)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_ITEM_SEARCH_CLICK_EVENT_CREATE

Authorizations:

JWT

header Parameters

Api-Version

required

string

Value: "4.4"

Request Body schema: application/json

required	object Additional parameters. Remember that you can use event enrichment to add the data automatically from a catalog. Aside from the required parameters (if any exist), all events accept custom, free-form parameters, with the following restrictions: WARNING: If you want to send the `email` param, it must be exactly the same as the email of the profile who generated the event. Some params are reserved for system use. If you send them in the `params` object, they are ignored or overwritten with system-assigned values: `modifiedBy` `apiKey` `eventUUID` `ip` `time` `businessProfileId`
label required	string non-empty This parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
required	object You must provide at least one of those profile identifiers.
time	string Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition. For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
eventSalt	string When an event has an `eventSalt`, it can be overwritten by sending another event. `eventSalt` must be unique in a workspace. An example of creating a salt is by generating a UUID or concatenating the profile ID, event's name, and timestamp, including milliseconds. This creates a value whose possibility of being duplicated is practically zero. To overwrite an event with another one, the new event MUST: have the same `eventSalt` as the original event have the same date and time as the original event (If the date and time don't match the original event, event salt doesn't have any effect.) belong to the same `clientId` as the original event have the same action (event name) as the original event IMPORTANT: DO NOT send the same `eventSalt` to different profiles! DO NOT send the same `eventSalt` with a different action! Pay attention to timezones - more details in the description of the `time` property (in v4/transactions events, it's called `recordedAt`). If you send a future time in an event, it is rejected and the current time is assigned automatically. This means it's impossible to use event salt with future times. Overwriting an event by using the event salt doesn't trigger automations. An event without an `eventSalt` can't be overwritten. The parameter cannot be added to an event at a later time. The parameter can't be retrieved later. You must keep track of the values that you send.

Responses

Request samples

Content type

application/json

{"params": {"item": "string",
"correlationId": "string",
"position": 0,
"searchType": "full-text-search"
},
"label": "Human-readable label",
"client": {"customId": "string",
"id": 0,
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"email": "string"
},
"time": "2019-02-07T09:53:56.999+00:00",
"eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00"
}

Response samples

400
401
403
415

Content type

application/json

{"timestamp": "2018-06-07T07:28:26.078+00:00",
"status": 400,
"error": "Bad Request",
"message": "Version header content is invalid",
"path": "/path_of_the_endpoint"
}