API docs by Redocly

Profile Management (May 27, 2025, 10:57:43 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.

Authorization

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

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

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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

object

Marketing agreements of the Profile.

You can also pass the values as strings ("true";"TRUE";"True"/"false";"FALSE";"False") or integers (1 for true and 0 for false).

object

Custom attributes (with any names)

tags
Array of strings

Tags can be used to group Profile accounts.

Responses

Request samples

Content type
application/json
{
  • "apiKey": "string",
  • "identityProvider": "SYNERISE",
  • "identityProviderToken": "string",
  • "email": "string",
  • "customId": null,
  • "password": "string",
  • "uuid": "string",
  • "deviceId": "string",
  • "agreements": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

object

Marketing agreements of the Profile.

You can also pass the values as strings ("true";"TRUE";"True"/"false";"FALSE";"False") or integers (1 for true and 0 for false).

object

Custom attributes (with any names)

tags
Array of strings

Tags can be used to group Profile accounts.

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": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

object

Marketing agreements of the Profile.

You can also pass the values as strings ("true";"TRUE";"True"/"false";"FALSE";"False") or integers (1 for true and 0 for false).

object

Custom attributes (with any names)

tags
Array of strings

Tags can be used to group Profile accounts.

Responses

Request samples

Content type
application/json
{
  • "apiKey": "string",
  • "identityProvider": "SYNERISE",
  • "identityProviderToken": "string",
  • "email": "string",
  • "customId": null,
  • "password": "string",
  • "uuid": "string",
  • "deviceId": "string",
  • "agreements": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "conditions": [
    ],
  • "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

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

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"
}

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

Content type
application/json
{
  • "consumer": {
    },
  • "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

Content type
application/json
{
  • "consumer": {
    },
  • "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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "consumer": {
    },
  • "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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "selected": true,
  • "data": {
    }
}

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

Content type
application/json
{
  • "token": "string"
}

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

Profile's email address

password
string

Password for the Profile

phone
string

Phone number of the Profile. Can only include digits, spaces, and an optional + at the beginning

customId
string

Profile's custom ID

firstName
string

Profile's first name

lastName
string

Profile's last name

displayName
string

Currently unused

uuid
string

UUID of the Profile

avatarUrl
string or null

URL of the Profile's avatar picture

birthDate
string

Profile's date of birth

company
string

Profile's company

city
string

Profile's city of residence

address
string

Profile's street address

zipCode
string

Profile's zip code

province
string

Profile's province of residence

countryCode
string

Code of Profile's country of residence (Alpha-2 code according to ISO 3166-1)

sex
string
Enum: "FEMALE" "MALE" "NOT_SPECIFIED" "OTHER"

Profile's sex

object

Marketing agreements of the Profile.

You can also pass the values as strings ("true";"TRUE";"True"/"false";"FALSE";"False") or integers (1 for true and 0 for false).

object

Custom attributes (with any names)

tags
Array of strings

Tags can be used to group Profile accounts.

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": "string",
  • "company": "string",
  • "city": "string",
  • "address": "string",
  • "zipCode": "string",
  • "province": "string",
  • "countryCode": "PL",
  • "sex": "FEMALE",
  • "agreements": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

email
string

Profile's email address

pinCode
string

The PIN code received by email

uuid
string

UUID of the Profile

Responses

Request samples

Content type
application/json
{
  • "deviceId": "string",
  • "email": "string",
  • "pinCode": "string",
  • "uuid": "07243772-008a-42e1-ba37-c3807cebde8f"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

Profile's email address

deviceId
string

Unique Android or iOS device ID.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

uuid
string

UUID of the Profile

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "deviceId": "string",
  • "uuid": "07243772-008a-42e1-ba37-c3807cebde8f"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

uuid
string

UUID of the Client

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "deviceId": "string",
  • "uuid": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "status": 0,
  • "timestamp": "string",
  • "path": "string",
  • "traceId": "string"
}

Profile management

Manage Profile details

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "base": {
    },
  • "tags": [
    ]
}

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": [
    ]
}

Response samples

Content type
application/json
{
  • "base": {
    },
  • "tags": [
    ]
}

List Profiles Deprecated

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

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": [
    ]
}

Response samples

Content type
application/json
{
  • "base": {
    },
  • "tags": [
    ]
}

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "base": {
    },
  • "tags": [
    ]
}

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "base": {
    },
  • "tags": [
    ]
}

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "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 REPLACE_BEARER_TOKEN'

Response samples

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 REPLACE_BEARER_TOKEN'

Response samples

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "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

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

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "materializationId": 0,
  • "customers": [
    ],
  • "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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "last_activity_date": "2019-08-24T14:15:22Z"
}

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

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "status": 0,
  • "timestamp": "string",
  • "path": "string",
  • "traceId": "string"
}

List profiles

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

This endpoint is limited to downloading the data of the first 10 000 profiles in the database, regardless of the pagination settings. To get the data of more profiles, use one of the export options, such as those offered by Automation or the client-exporter service.

  • 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 REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
[
  • {
    }
]

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. Must be a date in the past.
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": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

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": [
    ]
}

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. Must be a date in the past.
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": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

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": [
    ]
}

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/434428563 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

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": [
    ]
}

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/customIdExample,customIdExample2,customIdExample3,customIdExample4,customIdExample5/to/custom-id/customIdExample' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "clientId": 433230297,
  • "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": {
    },
  • "attributes": {
    },
  • "tags": [
    ],
  • "previousClients": [
    ],
  • "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/434428563,33322211,232212342/to/id/434428563' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "clientId": 433230297,
  • "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": {
    },
  • "attributes": {
    },
  • "tags": [
    ],
  • "previousClients": [
    ],
  • "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. Must be a date in the past.
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
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

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/434428563 \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "clientId": 433230297,
  • "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": {
    },
  • "attributes": {
    },
  • "tags": [
    ],
  • "previousClients": [
    ],
  • "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. Must be a date in the past.
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": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

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": [
    ]
}

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/434428563 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

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": [
    ]
}

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. Must be a date in the past.
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": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

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": [
    ]
}

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. Must be a date in the past.
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": {
    },
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

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": [
    ]
}

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/customIdExample \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

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": [
    ]
}

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/by-email/address@domain.com \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "clientId": 433230297,
  • "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": {
    },
  • "attributes": {
    },
  • "tags": [
    ],
  • "previousClients": [
    ],
  • "lastActivityDate": "2019-03-19T14:05:39Z"
}

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

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

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 REPLACE_BEARER_TOKEN'

Response samples

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

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 REPLACE_BEARER_TOKEN'

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

Necessary for backwards compatibility. Send empty array.

Responses

Request samples

Content type
application/json
{
  • "name": "Sample export",
  • "fields": [
    ],
  • "agreementFilter": "NONE",
  • "segmentationHash": "a0640816-8092-4a17-b41e-cd9e1230a3c7",
  • "expressions": [
    ],
  • "aggregates": [
    ],
  • "excludedIds": [ ]
}

Response samples

Content type
application/json
{
  • "taskId": 546,
  • "columnOrder": [
    ],
  • "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/546?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

Profile account management

As a Profile, manage your own account data

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

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

Responses

Request samples

Content type
application/json
{
  • "oldPassword": "test1.1234",
  • "password": "Test.1234",
  • "deviceId": "optional"
}

Response samples

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

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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

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

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

deviceId
string

Unique Android or iOS device ID.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

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

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

deviceId
string

Unique Android or iOS device ID.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
  • "deviceId": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

deviceId
string

Unique Android or iOS device ID.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

customId
string

Profile's custom ID

Responses

Request samples

Content type
application/json
{
  • "accessToken": "string",
  • "uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
  • "deviceId": "string",
  • "customId": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

deviceId
string

Unique Android or iOS device ID.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

customId
string

Profile's custom ID

Responses

Request samples

Content type
application/json
{
  • "accessToken": "string",
  • "uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
  • "deviceId": "string",
  • "customId": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

deviceId
string

Unique Android or iOS device ID.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

Responses

Request samples

Content type
application/json
{
  • "facebookToken": "string",
  • "uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
  • "deviceId": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "uuid": "string",
  • "deviceId": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "errors": [
    ],
  • "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

deviceId
string

Unique Android or iOS device ID.

We recommend sending this attribute every time, to assign a web push registration to the device.

Required when any form of unknown device control is enabled.

Responses

Request samples

Content type
application/json
{
  • "email": "newEmail",
  • "password": "my_password",
  • "uuid": "my_uuid",
  • "deviceId": "optional"
}

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 REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
{
  • "clientId": 433230297,
  • "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": {
    },
  • "attributes": {
    },
  • "tags": [
    ],
  • "previousClients": [
    ],
  • "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. Must be a date in the past.
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": {
    },
  • "attributes": {
    },
  • "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

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": [
    ]
}

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

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

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 devices

Link devices to profiles and manage push tokens

Clean up web push tokens

Remove mobile push Firebase tokens from profile. You can use this endpoint to clean up tokens updated before a selected date or by service worker version.

Using this endpoint generates a webpush.tokenDelete event for each deleted token.

If no tokens are left after the clean-up, the has_webpush_devices attribute in the profile is set to false.

  • 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: PUSH_DEVICES_SERVICE_WEB_PUSH_DEVICES_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_DETAIL

Authorizations:
JWT
path Parameters
clientId
required
integer <int64>

Unique identifier of a profile

Request Body schema: application/json
One of
type
required
string
Value: "BY_UPDATED_BEFORE"
updated
required
string <date-time>

Tokens updated before this date will be deleted.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "BY_UPDATED_BEFORE",
  • "updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "httpStatus": 0,
  • "errorCode": "string",
  • "timestamp": "string",
  • "message": "string",
  • "traceId": "string"
}

Clean up mobile push tokens

Remove mobile push Firebase tokens from profile. You can use this endpoint to clean up tokens updated before a selected date.

Using this endpoint generates a push.tokenDelete event for each deleted token.

If no tokens are left after the clean-up, the has_mobile_push_devices attribute in the profile is set to false.

  • 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: PUSH_DEVICES_SERVICE_MOBILE_PUSH_DEVICES_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_DETAIL

Authorizations:
JWT
path Parameters
clientId
required
integer <int64>

Unique identifier of a profile

Request Body schema: application/json
type
required
string
Value: "BY_UPDATED_BEFORE"
updated
required
string <date-time>

Tokens updated before this date will be deleted.

Responses

Request samples

Content type
application/json
{
  • "type": "BY_UPDATED_BEFORE",
  • "updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "httpStatus": 0,
  • "errorCode": "string",
  • "timestamp": "string",
  • "message": "string",
  • "traceId": "string"
}

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

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": [
    ]
}

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

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": [
    ]
}

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

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": [
    ]
}

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 REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

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

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/645 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "error": "string",
  • "status": 0,
  • "timestamp": "string",
  • "path": "string",
  • "message": "string",
  • "errors": [
    ]
}

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/434428563/tags \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

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/434428563/tags/645

Response samples

Content type
application/json
{
  • "clientId": 433230297,
  • "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/434428563/tags/645

Response samples

Content type
application/json
{
  • "error": "string",
  • "status": 0,
  • "timestamp": "string",
  • "path": "string",
  • "message": "string",
  • "errors": [
    ]
}

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

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:

  1. You create a transaction with items A, B, and C (in that order).
  2. You update the transaction and the items are now A, B, D, and C (in that order).
  3. 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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.

Responses

Request samples

Content type
application/json
{
  • "client": {
    },
  • "discountAmount": {
    },
  • "metadata": { },
  • "orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
  • "paymentInfo": {
    },
  • "products": [
    ],
  • "recordedAt": "2019-02-07T09:53:56.999+00:00",
  • "revenue": {
    },
  • "value": {
    },
  • "source": "MOBILE",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00"
}

Response samples

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

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:

  1. You create a transaction with items A, B, and C (in that order).
  2. You update the transaction and the items are now A, B, D, and C (in that order).
  3. 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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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": [
    ]
}

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/434428563?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 REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
[
  • {
    }
]

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 REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Response samples

Content type
application/json
[
  • {
    }
]

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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": [
    ]
}

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": {
    }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00",
  • "params": { }
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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": {
    },
  • "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

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.
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
[
  • {
    }
]

Response samples

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 REPLACE_BEARER_TOKEN'

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.

Responses

Request samples

Content type
application/json
{
  • "params": {
    },
  • "label": "Human-readable label",
  • "client": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00"
}

Response samples

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. The event's UUID stays the same.

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.
  • 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.
  • In Automations that use the overwritten event as a trigger, the automation is triggered if the new event is sent more than 72 hours after the original. This is because the event UUID stays the same, and Automation treats events with the same UUID within 72 hours as duplicates that were sent due to an error.

Responses

Request samples

Content type
application/json
{
  • "params": {
    },
  • "label": "Human-readable label",
  • "client": {
    },
  • "time": "2019-02-07T09:53:56.999+00:00",
  • "eventSalt": "972346context.action2019-02-07T09:53:56.999+00:00"
}

Response samples

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"
}