Profile Management — API Reference

Manage Profiles, their attributes, agreements, and consents

89 endpoints across 6 tags.

Profile registration

POST /sauth/clients/registered — Register a Profile

/api-reference/profile-management#tag/Profile-registration/operation/RegisterAClient

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: Anonymous Profile, Workspace (Business Profile)

API key permission required: SAUTH_REGISTER_CLIENT_CREATE

Request body (required)

application/json · sauth-RegisterAClientRequestBody

FieldTypeRequiredDescription
emailstringoptionalProfile's email address
passwordstringoptionalPassword for the Profile
phonestringoptionalPhone number of the Profile. Can only include digits, spaces, and an optional + at the beginning
customIdstringoptionalProfile's custom ID
firstNamestringoptionalProfile's first name
lastNamestringoptionalProfile's last name
displayNamestringoptionalCurrently unused
uuidstringoptionalUUID of the Profile
avatarUrlstringoptionalURL of the Profile's avatar picture
whatsAppIdstringoptionalWhatsApp identifier of the Profile
birthDatestringoptionalProfile's date of birth
companystringoptionalProfile's company
citystringoptionalProfile's city of residence
addressstringoptionalProfile's street address
zipCodestringoptionalProfile's zip code
provincestringoptionalProfile's province of residence
countryCodestringoptionalCode of Profile's country of residence (Alpha-2 code according to ISO 3166-1)
sexenum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">optionalProfile's sex
agreementsobjectoptionalMarketing 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).
attributesobjectoptionalCustom attributes (with any names) WARNING: Some attributes cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the attributes object. Click to expand the list of reserved attributes emailidclientIdphonecustomIduuidfirstNamelastName displayNamecompanyaddresscityprovincezipCodecountryCode birthDatesexavatarUrlanonymousagreementstagsbusinessProfileId timeipsourcenewsletter_agreementcustom_identifyfirstname lastnamecreatedupdatedlast_activity_datebirthdateexternal_avatar_url displaynamereceive_smsesreceive_push_messagesreceive_webpush_messages receive_btooth_messagesreceive_rfid_messagesreceive_wifi_messagesreceive_whatsapp_messageswhatsapp_id zipCodeanonymous_typecountry_idgeo_loc_countrygeo_loc_isp geo_loc_latgeo_loc_lonclub_card_idtypeconfirmedfacebookIddeletedAtdeleted_uniquestatusrecognizedprevious_clientstestProfile apikeyapiKeyApiKeyApikeytrackersnr_sdk_version eventCreateTimecorrelationId
tagsarray<string>optionalTags can be used to group Profile accounts.

Responses

StatusDescription
202Request accepted
400 application/jsonProfile already exists or request body malformed
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInsufficient permissions or wrong JWT scope (for example, profile token where a workspace token was required)
424 application/jsonOnly if customId was obtained from loyalty card code pool: provided customId does not exist in loyalty card code pool

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/registered \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","password":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","whatsAppId":"string","birthDate":"string","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","agreements":{"email":true,"sms":true,"push":true,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}'

POST /sauth/clients/activation/by-pin-code/confirmation — Confirm registration with PIN code

/api-reference/profile-management#tag/Profile-registration/operation/confirmByPinCodeUsingPOST

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

API consumer: Anonymous Profile

Request body

application/json · sauth-PinCodeConfirmationRequest

FieldTypeRequiredDescription
deviceIdstringoptionalUnique 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.
emailstringoptionalProfile's email address
pinCodestringoptionalThe PIN code received by email
uuidstringoptionalUUID of the Profile

Responses

StatusDescription
200OK, account confirmed
400 application/jsonRequest failed, see error message for details
401 application/jsonJWT missing, expired, or invalid
403 application/jsonRequest failed, see error message for details
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/activation/by-pin-code/confirmation \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"deviceId":"string","email":"string","pinCode":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f"}'

POST /sauth/clients/activation/by-pin-code/request — Re-send PIN code

/api-reference/profile-management#tag/Profile-registration/operation/resendByPinCodeUsingPOST

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

API consumer: Anonymous Profile

Request body

application/json · sauth-ClientPinActivationResendRequest

FieldTypeRequiredDescription
emailstringoptionalProfile's email address
deviceIdstringoptionalUnique 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.
uuidstringoptionalUUID of the Profile

Responses

StatusDescription
200OK
400 application/jsonRequest failed, see error message for details
401 application/jsonJWT missing, expired, or invalid
403 application/jsonRequest failed, see error message for details
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/activation/by-pin-code/request \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","deviceId":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f"}'

POST /sauth/clients/activation/confirmation — Activate a Profile's account

/api-reference/profile-management#tag/Profile-registration/operation/ConfirmAClientAccount

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

API consumers: Profile (Client), Anonymous Profile, Workspace (Business Profile)

API key permission required: SAUTH_CONFIRMATION_CLIENT_CREATE

Request body (required)

application/json · sauth-ConfirmAClientAccountRequestBody

FieldTypeRequiredDescription
tokenstringoptionalActivation token received by email

Responses

StatusDescription
200Request accepted
400 application/jsonRequest failed, see error message for details
401 application/jsonJWT missing, expired, or invalid
403 application/jsonRequest failed, see error message for details
409 application/jsonConflict
500 application/jsonInternal Server Error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/activation/confirmation \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"token":"string"}'

POST /sauth/clients/activation/request — Re-send email confirmation

/api-reference/profile-management#tag/Profile-registration/operation/resendUsingPOST

Request a re-sending of the confirmation email.

API consumers: Profile (Client), Anonymous Profile, Workspace (Business Profile)

API key permission required: SAUTH_CONFIRMATION_CLIENT_CREATE

Request body (required)

application/json · sauth-ClientActivationResendRequest

FieldTypeRequiredDescription
emailstringoptionalEmail address
deviceIdstringoptionalUnique 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.
uuidstringoptionalUUID of the Client

Responses

StatusDescription
200OK
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInsufficient permissions or wrong JWT scope (for example, profile token where a workspace token was required)
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/activation/request \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","deviceId":"string","uuid":"string"}'

Profile management

POST /v4/clients — Create or update a Profile

/api-reference/data-management#tag/Profile-management/operation/CreateAClientInCrm

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

This is an asynchronous operation. After the request body is validated, the request is added to the queue (HTTP 202).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_CLIENT_CREATE

User role permission required: client_management: create

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

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
FieldTypeRequiredDescription
emailstringoptionalThe 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. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
phonestringoptionalPhone 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
customIdstringoptionalA 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
firstNamestringoptionalProfile'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)
lastNamestringoptionalProfile'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)
displayNamestringoptionalCurrently unused
uuidstringoptionalUUID 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
avatarUrlstringoptionalURL 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)
birthDatestringoptionalDate 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.
companystringoptionalProfiles'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)
citystringoptionalProfile'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)
addressstringoptionalProfile'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)
zipCodestringoptionalProfile'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)
provincestringoptionalProfile'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)
countryCodestringoptionalCode of profile's country of residence in accordance with the ISO 3166 format
sexenum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">optionalProfile's sex
agreementsobjectoptionalThis 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).
attributesobjectoptionalThis 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 cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the attributes object. Click to expand the list of reserved attributes emailidclientIdphonecustomIduuidfirstNamelastName displayNamecompanyaddresscityprovincezipCodecountryCode birthDatesexavatarUrlanonymousagreementstagsbusinessProfileId timeipsourcenewsletter_agreementcustom_identifyfirstname lastnamecreatedupdatedlast_activity_datebirthdateexternal_avatar_url displaynamereceive_smsesreceive_push_messagesreceive_webpush_messages receive_btooth_messagesreceive_rfid_messagesreceive_wifi_messages zipCodeanonymous_typecountry_idgeo_loc_countrygeo_loc_isp geo_loc_latgeo_loc_lonclub_card_idtypeconfirmedfacebookIddeletedAtdeleted_uniquestatusrecognizedprevious_clientstestProfile apikeyapiKeyApiKeyApikeytrackersnr_sdk_versioneventCreateTimecorrelationId
tagsarray<string>optionalTags 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

StatusDescription
202Accepted, queued for processing
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","birthDate":"1987-10-24","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}'

POST /v4/clients/merge/from/custom-ids/{sourceCustomIDs}/to/custom-id/{targetCustomID} — Merge profiles by customId

/api-reference/data-management#tag/Profile-management/operation/MergeClientsByCustomId

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: Workspace (Business Profile)

API key permission required: API_MERGEBYCUSTOMID_CLIENT_UPDATE

Parameters

NameInTypeRequiredDescription
sourceCustomIDspathstringrequiredComma-delimited string with custom IDs of the profiles to merge
targetCustomIDpathstringrequiredThe custom ID of the profile to merge the sourceCustomIDs into
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
200 application/jsonRequest completed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonSource and/or target profile(s) not found.

Example request (cURL)

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'

POST /v4/clients/merge/from/ids/{fromClientIds}/to/id/{toClientId} — Merge profiles by clientId

/api-reference/data-management#tag/Profile-management/operation/MergeClientsByClientId

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: Workspace (Business Profile)

API key permission required: API_MERGE_BY_ID_CLIENT_UPDATE

Parameters

NameInTypeRequiredDescription
fromClientIdspathstringrequiredComma-delimited string with client IDs of the profiles to merge
toClientIdpathintegerrequiredThe ID of the profile to merge the fromClientIds into
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
200 application/jsonRequest completed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonSource and/or target profile(s) not found.

Example request (cURL)

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'

POST /v4/clients/batch — Batch add or update profiles

/api-reference/data-management#tag/Profile-management/operation/BatchAddOrUpdateClients

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.

This is an asynchronous operation. After the request body is validated, the request is added to the queue (HTTP 202).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BATCH_CLIENT_CREATE

User role permission required: client_management: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · array<object>

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)

Responses

StatusDescription
202Request accepted. IMPORTANT: this does not mean that all profiles were created/updated successfully. The data is sent for further processing in other elements of the infrastructure.
207 application/jsonInvalid data in some entries. Correct entries are sent for further processing, the invalid ones are rejected.
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients/batch \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"clientId":0,"email":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","birthDate":"1987-10-24","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}]'

GET /v4/clients/{clientId} — Get profile data

/api-reference/data-management#tag/Profile-management/operation/GetClientData

Retrieve profile data by profile ID. If PII protection is enabled and your API key/user doesn't have the required permissions, this endpoint can only return test profiles; other profiles return error 404.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_ID_CLIENT_READ

User role permission required: client_info: read

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
200 application/jsonDetails of a single profile
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found or access blocked by PII protection settings

Example request (cURL)

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'

POST /v4/clients/{clientId} — Update a profile (identify by ID)

/api-reference/data-management#tag/Profile-management/operation/UpdateAClient

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.

This is an asynchronous operation. After the request body is validated, the request is added to the queue (HTTP 202).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_ID_CLIENT_UPDATE

User role permission required: client_info: update

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-CreateClientRequestBody-apiv4

FieldTypeRequiredDescription
emailstringoptionalThe 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. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
phonestringoptionalPhone 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
customIdstringoptionalA 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
firstNamestringoptionalProfile'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)
lastNamestringoptionalProfile'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)
displayNamestringoptionalCurrently unused
uuidstringoptionalUUID 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
avatarUrlstringoptionalURL 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)
birthDatestringoptionalDate 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.
companystringoptionalProfiles'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)
citystringoptionalProfile'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)
addressstringoptionalProfile'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)
zipCodestringoptionalProfile'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)
provincestringoptionalProfile'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)
countryCodestringoptionalCode of profile's country of residence in accordance with the ISO 3166 format
sexenum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">optionalProfile's sex
agreementsobjectoptionalThis 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).
attributesobjectoptionalThis 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 cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the attributes object. Click to expand the list of reserved attributes emailidclientIdphonecustomIduuidfirstNamelastName displayNamecompanyaddresscityprovincezipCodecountryCode birthDatesexavatarUrlanonymousagreementstagsbusinessProfileId timeipsourcenewsletter_agreementcustom_identifyfirstname lastnamecreatedupdatedlast_activity_datebirthdateexternal_avatar_url displaynamereceive_smsesreceive_push_messagesreceive_webpush_messages receive_btooth_messagesreceive_rfid_messagesreceive_wifi_messages zipCodeanonymous_typecountry_idgeo_loc_countrygeo_loc_isp geo_loc_latgeo_loc_lonclub_card_idtypeconfirmedfacebookIddeletedAtdeleted_uniquestatusrecognizedprevious_clientstestProfile apikeyapiKeyApiKeyApikeytrackersnr_sdk_versioneventCreateTimecorrelationId
tagsarray<string>optionalTags 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

StatusDescription
202Accepted, queued for processing
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients/434428563 \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","birthDate":"1987-10-24","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}'

DELETE /v4/clients/{clientId} — Delete a profile

/api-reference/data-management#tag/Profile-management/operation/DeleteAClient

Delete a profile from the database.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_ID_CLIENT_DELETE

User role permission required: client_info: delete

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
202Accepted
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found

Example request (cURL)

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'

POST /v4/clients/by-email/{clientEmail} — Update a profile (identify by email)

/api-reference/data-management#tag/Profile-management/operation/UpdateAClientByEmail

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.

This is an asynchronous operation. After the request body is validated, the request is added to the queue (HTTP 202).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_EMAIL_CLIENT_UPDATE

User role permission required: client_info: update

Parameters

NameInTypeRequiredDescription
clientEmailpathstringrequiredThe 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-CreateClientRequestBody-apiv4

FieldTypeRequiredDescription
emailstringoptionalThe 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. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
phonestringoptionalPhone 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
customIdstringoptionalA 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
firstNamestringoptionalProfile'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)
lastNamestringoptionalProfile'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)
displayNamestringoptionalCurrently unused
uuidstringoptionalUUID 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
avatarUrlstringoptionalURL 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)
birthDatestringoptionalDate 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.
companystringoptionalProfiles'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)
citystringoptionalProfile'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)
addressstringoptionalProfile'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)
zipCodestringoptionalProfile'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)
provincestringoptionalProfile'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)
countryCodestringoptionalCode of profile's country of residence in accordance with the ISO 3166 format
sexenum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">optionalProfile's sex
agreementsobjectoptionalThis 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).
attributesobjectoptionalThis 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 cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the attributes object. Click to expand the list of reserved attributes emailidclientIdphonecustomIduuidfirstNamelastName displayNamecompanyaddresscityprovincezipCodecountryCode birthDatesexavatarUrlanonymousagreementstagsbusinessProfileId timeipsourcenewsletter_agreementcustom_identifyfirstname lastnamecreatedupdatedlast_activity_datebirthdateexternal_avatar_url displaynamereceive_smsesreceive_push_messagesreceive_webpush_messages receive_btooth_messagesreceive_rfid_messagesreceive_wifi_messages zipCodeanonymous_typecountry_idgeo_loc_countrygeo_loc_isp geo_loc_latgeo_loc_lonclub_card_idtypeconfirmedfacebookIddeletedAtdeleted_uniquestatusrecognizedprevious_clientstestProfile apikeyapiKeyApiKeyApikeytrackersnr_sdk_versioneventCreateTimecorrelationId
tagsarray<string>optionalTags 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

StatusDescription
202Accepted, queued for processing
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients/by-email/clientemail@synerise.com \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","birthDate":"1987-10-24","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}'

POST /v4/clients/by-customid/{customId} — Update a profile (identify by customId)

/api-reference/data-management#tag/Profile-management/operation/UpdateAClientByCustomId

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.

This is an asynchronous operation. After the request body is validated, the request is added to the queue (HTTP 202).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_CUSTOM_ID_CLIENT_UPDATE

User role permission required: client_info: update

Parameters

NameInTypeRequiredDescription
customIdpathstringrequiredThe custom ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-CreateClientRequestBody-apiv4

FieldTypeRequiredDescription
emailstringoptionalThe 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. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
phonestringoptionalPhone 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
customIdstringoptionalA 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
firstNamestringoptionalProfile'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)
lastNamestringoptionalProfile'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)
displayNamestringoptionalCurrently unused
uuidstringoptionalUUID 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
avatarUrlstringoptionalURL 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)
birthDatestringoptionalDate 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.
companystringoptionalProfiles'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)
citystringoptionalProfile'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)
addressstringoptionalProfile'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)
zipCodestringoptionalProfile'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)
provincestringoptionalProfile'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)
countryCodestringoptionalCode of profile's country of residence in accordance with the ISO 3166 format
sexenum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">optionalProfile's sex
agreementsobjectoptionalThis 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).
attributesobjectoptionalThis 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 cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the attributes object. Click to expand the list of reserved attributes emailidclientIdphonecustomIduuidfirstNamelastName displayNamecompanyaddresscityprovincezipCodecountryCode birthDatesexavatarUrlanonymousagreementstagsbusinessProfileId timeipsourcenewsletter_agreementcustom_identifyfirstname lastnamecreatedupdatedlast_activity_datebirthdateexternal_avatar_url displaynamereceive_smsesreceive_push_messagesreceive_webpush_messages receive_btooth_messagesreceive_rfid_messagesreceive_wifi_messages zipCodeanonymous_typecountry_idgeo_loc_countrygeo_loc_isp geo_loc_latgeo_loc_lonclub_card_idtypeconfirmedfacebookIddeletedAtdeleted_uniquestatusrecognizedprevious_clientstestProfile apikeyapiKeyApiKeyApikeytrackersnr_sdk_versioneventCreateTimecorrelationId
tagsarray<string>optionalTags 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

StatusDescription
202Accepted, queued for processing
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients/by-customid/customIdExample \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","phone":"+48111222333","customId":"string","firstName":"string","lastName":"string","displayName":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","avatarUrl":"string","birthDate":"1987-10-24","company":"string","city":"string","address":"string","zipCode":"string","province":"string","countryCode":"PL","sex":"FEMALE","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"tags":["string"]}'

DELETE /v4/clients/by-custom-id/{customId} — Delete a profile (identify by customId)

/api-reference/data-management#tag/Profile-management/operation/DeleteAClientByCustomId

Delete a profile from the database.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_ID_CLIENT_DELETE

User role permission required: client_info: delete

Parameters

NameInTypeRequiredDescription
customIdpathstringrequiredThe custom ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
202Accepted
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found

Example request (cURL)

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'

GET /v4/clients/{identifierType}/{identifierValue} — Fetch profile data

/api-reference/data-management#tag/Profile-management/operation/FindAClient

Get the details of a single profile. If PII protection is enabled and your API key/user doesn't have the required permissions, this endpoint can only return test profiles; other profiles return error 404.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_IDENTIFIER_CLIENT_READ

User role permission required: client_info: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"by-custom-id", "by-phone", "by-uuid", "by-email">requiredThe type of profile identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier. The value must be URL-encoded.
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
200 application/jsonDetails of a single profile
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found or access blocked by PII protection settings
415 application/jsonUnsupported Media Type

Example request (cURL)

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'

GET /v4/clients/batch/by-phone/{phoneNumber} — Batch fetch profiles by phone number

/api-reference/data-management#tag/Profile-management/operation/FindClientsByPhone

Returns a detailed list of profiles associated with the provided phone number. The number saved in the profile must exactly match the number from the request. If no profiles match the criteria, an empty list is returned.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_BY_IDENTIFIER_CLIENT_READ

User role permission required: client_info: read

Parameters

NameInTypeRequiredDescription
phoneNumberpathstringrequiredThe phone number to search for in profiles. Must be an exact match. The value must be URL-encoded. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
200 application/jsonReturns an array of profile details.
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found or access blocked by PII protection settings
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/clients/batch/by-phone/12065550100 \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

GET /crm/v1/clients/{clientId}/contacts — Get Profile details (deprecated)

/api-reference/data-management#tag/Profile-management/operation/getClient

This method is deprecated. It will be disabled on August 30, 2026.

You can use these methods instead:

Retrieve the details of a Profile.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CRM_DETAILS_CLIENT_READ

User role permission required: client_info: read

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredProfile ID Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.

Responses

StatusDescription
200 application/jsonProfile details
404 text/plainResource not found or access blocked by PII protection settings

Example request (cURL)

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

PUT /crm/v1/contacts/{clientId} — Update Profile (deprecated)

/api-reference/data-management#tag/Profile-management/operation/updateClient

This method is deprecated. It will be disabled on August 16, 2026
Use one of these endpoints instead:

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: Synerise User, Workspace (Business Profile)

API key permission required: CRM_CLIENT_UPDATE

User role permission required: client_management: update

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredProfile ID Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.

Request body (required)

application/json · crm-CustomerCommon

FieldTypeRequiredDescription
uuidstringoptionalUUID of the Profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
emailstringoptionalProfile's e-mail address Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
firstnamestringoptionalProfile's first name
lastNamestringoptionalProfile's last name
custom_identifystringoptionalA custom ID for the Profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
companystringoptionalProfile's company
phonestringoptionalProfile's phone number Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
addressstringoptionalProfile's street address
birthdatestringoptionalProfile's date of birth. Must be a past date.
citystringoptionalProfile's city of residence
zipCodestringoptionalProfile's zip code
provincestringoptionalProfile's province of residence
country_idstringoptionalID of the Profile's country of residence
countryCodestringoptionalCode of Profile's country of residence
avatarUrlstringoptionalURL of the Profile's avatar picture
sexenum<"0", "1", "2", "3">optionalProfile's sex. 0: undefined 1: female 2: male 3: other
tagsarray<string>optionalCustom tags. They can be used, for example, to group Profiles.
additionalPropertiesoptionalAdditional attributes, including custom attributes. The following attributes are reserved for system use and can't be modified: Click to expand the list of reserved attributes emailclientIdphonecustomIduuidfirstNamelastNamedisplayNamecompanyaddresscityprovincezipCodecountryCodebirthDatesexavatarUrlanonymousagreementstagsbusinessProfileIdtimeipsourcenewsletter_agreementcustom_identifyfirstnamelastnamecreatedupdatedlast_activity_datebirthdateexternal_avatar_urldisplaynamereceive_smsesreceive_push_messagesreceive_webpush_messagesreceive_btooth_messagesreceive_rfid_messagesreceive_wifi_messagesconfirmation_hashownerIdzipCodeanonymous_typecountry_idgeo_loc_citygeo_loc_countrygeo_loc_asgeo_loc_country_codegeo_loc_ispgeo_loc_latgeo_loc_longeo_loc_orggeo_loc_querygeo_loc_regiongeo_loc_region_namegeo_loc_statusgeo_loc_timezonegeo_loc_zipclub_card_idtypeconfirmedfacebookIdstatus

Responses

StatusDescription
200 application/jsonProfile details

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/crm/v1/contacts/%7BclientId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string","firstname":"string","lastName":"string","custom_identify":"string","company":"string","phone":"string","address":"string","birthdate":"2019-08-24","city":"string","zipCode":"string","province":"string","country_id":"string","countryCode":"PL","avatarUrl":"string","sex":"0","tags":["string"],"additionalProperties":null}'

POST /morph/exports/clients/segmentation — Create and run profile export

/api-reference/data-management#tag/Profile-management/operation/runProfileExport

Request an export of profiles. The group of profiles to export is selected by pointing to a segmentation. After the export is completed, you can access the data with GET /exports/clients/{taskId}/data or from https://app.synerise.com/assets/exports.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CLIENT_EXPORTER_REPORT_CREATE

User role permission required: settings_export: create

Request body (required)

application/json · morph-NewProfileExport

FieldTypeRequiredDescription
namestringrequiredName of the export, visible at https://app.synerise.com/assets/
fieldsarray<string>requiredProfile attributes to export. The first attribute in this array MUST BE id
agreementFilterenum<"NONE", "EMAIL", "WEB_PUSH", "PUSH", …>requiredYou can filter the profiles by their marketing agreement. NONE means no filter.
segmentationHashstringrequiredUUID of the segmentation which defines the profiles to export. The segmentation conditions are checked at the time of sending the "create and run export" request.
tagsarray<string>optionalProfile tags to check for an exported profile. In the results, the tag name is the key and the value is "true" (string) if the tag is assigned to a given profile, otherwise it's "false".
expressionsarray<string>optionalUUIDs of expressions to check for an exported profile. In the results, the name of the expression is the key and the value is the result of the expression.
aggregatesarray<string>optionalUUIDs of aggregates to check for an exported profile. In the results, the name of the aggregate is the key and the value is the result of the aggregate.
segmentationsarray<string>optionalUUIDs of segmentations to check for an exported profile. In the results, the name of the segmentation is the key and the value is "true" (string) if the profile belongs to the segmentation, otherwise it's "false".
excludedIdsarray<number>requiredList of clientIds to exclude from the exported data

Responses

StatusDescription
200 application/jsonExport task created and queued
400 application/jsonInvalid request

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/morph/exports/clients/segmentation \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string","fields":["id","attr1","attr2"],"agreementFilter":"NONE","segmentationHash":"e7cff342-b484-4fcb-aa34-4735122bc9e7","tags":["string"],"expressions":["497f6eca-6276-4993-bfeb-53cbbbba6f08"],"aggregates":["497f6eca-6276-4993-bfeb-53cbbbba6f08"],"segmentations":["497f6eca-6276-4993-bfeb-53cbbbba6f08"],"excludedIds":[0]}'

GET /morph/exports/clients/{taskId}/status — Check profile export status

/api-reference/data-management#tag/Profile-management/operation/getProfileExportStatus

After creating an export with POST /exports/clients/segmentation, you can check its status. When the export is ready, you can access the data with GET /exports/clients/{taskId}/data.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CLIENT_EXPORTER_REPORT_CREATE

User role permission required: settings_export: create

Parameters

NameInTypeRequiredDescription
taskIdpathstringrequiredUnique ID of the export task

Responses

StatusDescription
200 application/jsonStatus of the export task

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/morph/exports/clients/%7BtaskId%7D/status \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /morph/exports/clients/{taskId}/data — Get exported profiles

/api-reference/data-management#tag/Profile-management/operation/getExportedProfileData

Get exported profiles as a list. To create the export, use POST /exports/clients/segmentation.

Tip: If you want to download a CSV, JSON, or JSONL, find your export in https://app.synerise.com/assets/exports.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CLIENT_EXPORTER_REPORT_CREATE

User role permission required: settings_export: create

Parameters

NameInTypeRequiredDescription
taskIdpathstringrequiredUnique ID of the export task
offsetquerynumberrequiredThe index of the first record to retrieve. Use this to paginate the exported data.
limitqueryintegerrequiredThe number of records to retrieve. Use this to paginate the exported data.

Responses

StatusDescription
200 application/jsonExported profile data
400 application/jsonInvalid request

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/morph/exports/clients/%7BtaskId%7D/data?offset=SOME_NUMBER_VALUE&limit=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /notes-service/by-id/{clientId} — Get all Profile notes

/api-reference/data-management#tag/Profile-management/operation/getAllNotesUsingGET

Retrieve all notes associated with a single profile.

API consumer: Synerise User

User role permission required: client_notes: read

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredProfile ID

Responses

StatusDescription
200 application/jsonAn array of notes
401Unauthorized
403Forbidden
404Not Found

Example request (cURL)

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

POST /notes-service/by-id/{clientId} — Create a note

/api-reference/data-management#tag/Profile-management/operation/createNoteUsingPOST

Create a new note in the profile

API consumer: Synerise User

User role permission required: client_notes: create

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredProfile ID

Request body

application/json · notes-service-NoteRequest

FieldTypeRequiredDescription
subjectstringoptionalThe title of the note
bodystringoptionalText of the note

Responses

StatusDescription
200 application/jsonOK
201Created
401Unauthorized
403Forbidden
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/notes-service/by-id/%7BclientId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"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"}'

GET /notes-service/by-id/{clientId}/{noteId} — Get note

/api-reference/data-management#tag/Profile-management/operation/getNoteUsingGET

Retrieve a single note

API consumer: Synerise User

User role permission required: client_notes: read

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredProfile ID
noteIdpathstringrequiredNote UUID

Responses

StatusDescription
200 application/jsonOK
401Unauthorized
403Forbidden
404Not Found

Example request (cURL)

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

PUT /notes-service/by-id/{clientId}/{noteId} — Update note

/api-reference/data-management#tag/Profile-management/operation/updateNoteUsingPUT

You can update an existing note.

API consumer: Synerise User

User role permission required: client_notes: update

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredProfile ID
noteIdpathstringrequiredNote UUID

Request body

application/json · notes-service-NoteRequest

FieldTypeRequiredDescription
subjectstringoptionalThe title of the note
bodystringoptionalText of the note

Responses

StatusDescription
200 application/jsonOK
201Created
401Unauthorized
403Forbidden
404Not Found

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/notes-service/by-id/%7BclientId%7D/%7BnoteId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"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"}'

DELETE /notes-service/by-id/{clientId}/{noteId} — Delete note

/api-reference/data-management#tag/Profile-management/operation/deleteNoteUsingDELETE

You can delete a note. This operation is irreversible.

API consumer: Synerise User

User role permission required: client_notes: delete

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredProfile ID
noteIdpathstringrequiredNote UUID

Responses

StatusDescription
200OK
204No Content
401Unauthorized
403Forbidden

Example request (cURL)

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

POST /sauth/management/client/{clientID}/logout — Log out a Profile

/api-reference/data-management#tag/Profile-management/operation/logoutClientUsingPOST

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

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: SAUTH_LOGOUT_CLIENT_CREATE

User role permission required: settings_customers_iam: create

Parameters

NameInTypeRequiredDescription
clientIDpathstringrequiredThe ID of the Profile

Request body

application/json · sauth-ClientLogoutRequest

FieldTypeRequiredDescription
actionenum<"LOGOUT", "LOGOUT_WITH_SESSION_CLEARING">optional

Responses

StatusDescription
200OK
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInsufficient permissions or wrong JWT scope (for example, profile token where a workspace token was required)
404Profile not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/management/client/434428563/logout \
  --header 'content-type: application/json' \
  --data '{"action":"LOGOUT"}'

Profile account management

GET /v4/my-account/personal-information — Get Profile's own data

/api-reference/profile-management#tag/Profile-account-management/operation/getAccountDataGET

A Profile can retrieve its details from the database.

API consumers: Profile (Client), ANONYMOUS_CLIENT_CONDITIONAL

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required
Content-Typeheaderenum<"application/json">required

Responses

StatusDescription
200 application/jsonProfile information
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

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'

POST /v4/my-account/personal-information — Update Profile's own data

/api-reference/profile-management#tag/Profile-account-management/operation/updateAccountDataUsingPOST

A Profile can update its own details.

API consumer: Profile (Client)

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · api-service-ClientChangeset-apiv4

FieldTypeRequiredDescription
addressstringoptionalProfile'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)
agreementsobjectoptionalThis 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).
attributesobjectoptionalThis 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 cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the attributes object. Click to expand the list of reserved attributes emailidclientIdphonecustomIduuidfirstNamelastName displayNamecompanyaddresscityprovincezipCodecountryCode birthDatesexavatarUrlanonymousagreementstagsbusinessProfileId timeipsourcenewsletter_agreementcustom_identifyfirstname lastnamecreatedupdatedlast_activity_datebirthdateexternal_avatar_url displaynamereceive_smsesreceive_push_messagesreceive_webpush_messages receive_btooth_messagesreceive_rfid_messagesreceive_wifi_messages zipCodeanonymous_typecountry_idgeo_loc_countrygeo_loc_isp geo_loc_latgeo_loc_lonclub_card_idtypeconfirmedfacebookIddeletedAtdeleted_uniquestatusrecognizedprevious_clientstestProfile apikeyapiKeyApiKeyApikeytrackersnr_sdk_versioneventCreateTimecorrelationId
avatarUrlstringoptionalURL 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)
birthDatestringoptionalDate 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.
citystringoptionalProfile'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)
companystringoptionalProfiles'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)
countryCodestringoptionalCode of profile's country of residence in accordance with the ISO 3166 format
customIdstringoptionalA 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
displayNamestringoptionalCurrently unused
emailstringoptionalThe 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. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
firstNamestringoptionalProfile'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)
lastNamestringoptionalProfile'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)
phonestringoptionalPhone 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])/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
provincestringoptionalProfile'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)
sexenum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">optionalProfile's sex
zipCodestringoptionalProfile'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

StatusDescription
202Accepted
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --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: application/json' \
  --data '{"address":"string","agreements":{"email":false,"sms":false,"push":false,"webPush":false,"bluetooth":false,"rfid":false,"wifi":false},"attributes":{"property1":null,"property2":null},"avatarUrl":"string","birthDate":"1987-10-24","city":"string","company":"string","countryCode":"PL","customId":"string","displayName":"string","email":"string","firstName":"string","lastName":"string","phone":"+48111222333","province":"string","sex":"FEMALE","zipCode":"string"}'

POST /v4/my-account/phone-update/request — Request profile phone number change

/api-reference/profile-management#tag/Profile-account-management/operation/RequestClientPhoneNumberChange

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

API consumer: Profile (Client)

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
phonestringrequiredCurrent phone number of the profile. Must match the pattern (ECMA flavor): /(^\+[0-9 \-()/]{6,19}$)|(^[0-9 \-()/]{6,20}$)/

Responses

StatusDescription
202Request accepted'
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/my-account/phone-update/request \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"phone":"+48111222333"}'

POST /v4/my-account/phone-update/confirmation — Confirm profile phone number change

/api-reference/profile-management#tag/Profile-account-management/operation/ConfirmClientPhoneNumberChange

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

API consumer: Profile (Client)

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
phonestringrequiredNew phone number Must match the pattern (ECMA flavor): /(^\+[0-9 \-()/]{6,19}$)|(^[0-9 \-()/]{6,20}$)/ Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
confirmationCodestringrequiredConfirmation code received by text message
deviceIdstringoptionalUnique Android or iOS device ID
smsAgreementbooleanoptionalPermission to receive marketing information by SMS

Responses

StatusDescription
202Request accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/my-account/phone-update/confirmation \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"phone":"+48111222333","confirmationCode":"73AC1","deviceId":"string","smsAgreement":true}'

POST /sauth/clients/password-reset/request — Request Profile password reset

/api-reference/profile-management#tag/Profile-account-management/operation/RequestClientPasswordReset

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: Anonymous Profile, Workspace (Business Profile)

API key permission required: SAUTH_PASSWORD_RESET_CLIENT_CREATE

Request body (required)

application/json · sauth-RequestClientpasswordresetRequest

FieldTypeRequiredDescription
emailstringrequiredEmail address where the password reset link will be sent

Responses

StatusDescription
200Request accepted
201Created
401 application/jsonJWT missing, expired, or invalid
403 application/jsonForbidden
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/password-reset/request \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"testDoc@example.com"}'

POST /sauth/clients/password-reset/confirmation — Confirm Profile password reset

/api-reference/profile-management#tag/Profile-account-management/operation/ConfirmClientPasswordReset

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

API consumers: Anonymous Profile, Workspace (Business Profile)

API key permission required: SAUTH_PASSWORD_RESET_CLIENT_CREATE

Request body (required)

application/json · sauth-ConfirmClientpasswordresetRequest

FieldTypeRequiredDescription
passwordstringrequiredNew password
tokenstringrequiredToken received by email

Responses

StatusDescription
200Request accepted

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/password-reset/confirmation \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"password":"testPass1!","token":"token_from_pass_reset_req"}'

POST /sauth/my-account/change-password — Change Profile password

/api-reference/profile-management#tag/Profile-account-management/operation/ChangeClientPassword

A Profile can update the password to its account.

API consumer: Profile (Client)

Request body (required)

application/json · sauth-ChangeClientPasswordRequestBody

FieldTypeRequiredDescription
oldPasswordstringoptionalCurrent password
passwordstringoptionalNew password
deviceIdstringoptionalUnique 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

StatusDescription
200 text/plainRequest accepted
400 application/jsonBad Request

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/my-account/change-password \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"oldPassword":"string","password":"string","deviceId":"string"}'

POST /sauth/v2/my-account/delete — Delete account

/api-reference/profile-management#tag/Profile-account-management/operation/deleteAccountUsingPOST

A Profile can delete its own account. Its 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: Profile (Client)

Request body (required)

application/json · sauth-DeleteAccountV2RequestBody

FieldTypeRequiredDescription
passwordstringrequiredProfile password. Only applicable if the Profile is not authenticated by an external identity provider.
uuidstringoptionalUUID of the Profile
externalTokenstringoptionalExternal authorization token. Only applicable if the Profile is authenticated by an external identity provider.
customIdstringoptionalCustom ID of the Profile, if applicable
identityProviderenum<"FACEBOOK", "OAUTH", "APPLE", "SYNERISE">requiredAuthorization provider
deviceIdstringoptionalUnique 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

StatusDescription
200Account deleted
400 application/jsonRequest body malformed/invalid
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInvalid credentials in request body
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/v2/my-account/delete \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"password":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","externalToken":"string","customId":"string","identityProvider":"FACEBOOK","deviceId":"string"}'

POST /sauth/v2/my-account/email-change/request — Request Profile email change

/api-reference/profile-management#tag/Profile-account-management/operation/changeEmailRequestUsingPOST

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: Profile (Client)

Request body

application/json · sauth-GenericClientEmailChangeRequest

FieldTypeRequiredDescription
emailstringrequiredNew email address
externalTokenstringoptionalExternal authorization token. Only applicable if the Profile is authenticated by an external identity provider.
passwordstringoptionalProfile password. Only applicable if the Profile is not authenticated by an external identity provider.
uuidstringrequiredUUID of the Profile
deviceIdstringoptionalUnique 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.
customIdstringoptionalCustom ID of the Profile, if applicable

Responses

StatusDescription
200Email change requested, confirmation token sent to new email
400 application/jsonRequest body malformed/invalid
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInvalid credentials in request body
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/v2/my-account/email-change/request \
  --header 'content-type: application/json' \
  --data '{"email":"string","externalToken":"string","password":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","deviceId":"string","customId":"string"}'

POST /sauth/v3/my-account/logout — Log out a Profile

/api-reference/profile-management#tag/Profile-account-management/operation/logoutUsingPOST

Log out a Profile when authenticated as that Profile.

API consumers: Profile (Client), ANONYMOUS_CLIENT_CONDITIONAL

Request body

application/json · sauth-ClientLogoutRequest

FieldTypeRequiredDescription
actionenum<"LOGOUT", "LOGOUT_WITH_SESSION_CLEARING">optional

Responses

StatusDescription
200OK
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInsufficient permissions or wrong JWT scope (for example, profile token where a workspace token was required)
404Profile not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/v3/my-account/logout \
  --header 'content-type: application/json' \
  --data '{"action":"LOGOUT"}'

POST /sauth/my-account/email-change/confirmation — Confirm Profile email change

/api-reference/profile-management#tag/Profile-account-management/operation/confirmClientEmailChange

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: Profile (Client)

Request body (required)

application/json · sauth-ConfirmClientEmailChangeRequestBody

FieldTypeRequiredDescription
tokenstringoptionalToken received by email
newsletterAgreementbooleanoptionalPermission to receive email newsletters

Responses

StatusDescription
200Request accepted
400 application/jsonRequest body malformed/invalid
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInvalid confirmation token

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/my-account/email-change/confirmation \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"token":"58acd5bd-8efd-47ed-b101-32eb56e13839","newsletterAgreement":true}'

POST /sauth/clients/facebook/email-change/request — Change Facebook Profile email

/api-reference/profile-management#tag/Profile-account-management/operation/changeEmailUsingPOST

Change the email address of a Profile registered by Facebook

API consumer: Profile (Client)

Request body (required)

application/json · sauth-ClientEmailChangeRequest

FieldTypeRequiredDescription
emailstringoptionalNew email address
uuidstringoptionalUUID of the Profile
deviceIdstringoptionalUnique 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

StatusDescription
200OK
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInsufficient permissions or wrong JWT scope (for example, profile token where a workspace token was required)
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/facebook/email-change/request \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","deviceId":"string"}'

POST /sauth/clients/oauth/deleted — Delete Client Account (OAuth) (deprecated)

/api-reference/profile-management#tag/Profile-account-management/operation/deleteOauthClientUsingPOST

This endpoint is deprecated. Use this one.

A Client can delete their own account.

API consumer: Profile (Client)

Request body (required)

application/json · sauth-DeleteOauthClientRequestBody

FieldTypeRequiredDescription
accessTokenstringoptionalOAuth access token
uuidstringoptionalUUID of the Profile
deviceIdstringoptionalUnique 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.
customIdstringoptionalProfile's custom ID

Responses

StatusDescription
200OK
400 application/jsonRequest body malformed/invalid
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInvalid credentials in request body
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/oauth/deleted \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"accessToken":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","deviceId":"string","customId":"string"}'

POST /sauth/clients/apple/deleted — Delete Profile account (Sign in with Apple) (deprecated)

/api-reference/profile-management#tag/Profile-account-management/operation/deleteAppleClientUsingPOST

This endpoint is deprecated. Use this one.

A Profile can delete its own account.

API consumer: Profile (Client)

Request body (required)

application/json · sauth-DeleteAppleClientRequestBody

FieldTypeRequiredDescription
accessTokenstringoptionalApple access token
uuidstringoptionalUUID of the Profile
deviceIdstringoptionalUnique 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.
customIdstringoptionalProfile's custom ID

Responses

StatusDescription
200OK
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInsufficient permissions or wrong JWT scope (for example, profile token where a workspace token was required)
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/apple/deleted \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"accessToken":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","deviceId":"string","customId":"string"}'

POST /sauth/clients/facebook/deleted — Delete Facebook Profile Account (deprecated)

/api-reference/profile-management#tag/Profile-account-management/operation/DeleteAFacebookClientAccount

This endpoint is deprecated. Use this one.

A Profile can delete its own account.

API consumer: Profile (Client)

Request body (required)

application/json · sauth-DeleteAFacebookClientAccountRequestBody

FieldTypeRequiredDescription
facebookTokenstringoptionalFacebook authentication token
uuidstringoptionalUUID of the Profile
deviceIdstringoptionalUnique 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

StatusDescription
200Request accepted
400 application/jsonRequest body malformed/invalid
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInvalid credentials in request body
404Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/clients/facebook/deleted \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"facebookToken":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","deviceId":"string"}'

POST /sauth/my-account/delete — Delete account (deprecated)

/api-reference/profile-management#tag/Profile-account-management/operation/deleteAccountUsingPOST-v1

This endpoint is deprecated. Use this one.

A Profile can delete its own account.

API consumer: Profile (Client)

Request body

application/json · sauth-DeleteAccountV1RequestBody

FieldTypeRequiredDescription
passwordstringoptionalProfile password
uuidstringoptionalProfile UUID
deviceIdstringoptionalUnique 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

StatusDescription
200OK
400 application/jsonRequest body malformed/invalid
401 application/jsonJWT missing, expired, or invalid
403 application/jsonInvalid credentials in request body

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/my-account/delete \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"password":"string","uuid":"string","deviceId":"string"}'

POST /sauth/my-account/email-change/request — Request Profile email change (deprecated)

/api-reference/profile-management#tag/Profile-account-management/operation/requestClientEmailChange

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: Profile (Client)

Request body (required)

application/json · sauth-RequestClientEmailChangeRequestBody

FieldTypeRequiredDescription
emailstringoptionalNew email address
passwordstringoptionalProfile password
uuidstringoptionalUUID of the Profile
deviceIdstringoptionalUnique 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

StatusDescription
202Request accepted
400Clients not recognizable by email

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/sauth/my-account/email-change/request \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email":"string","password":"string","uuid":"07243772-008a-42e1-ba37-c3807cebde8f","deviceId":"string"}'

Profile devices

POST /v4/clients/{clientId}/linked-devices — Link a device by profile ID

/api-reference/profile-management#tag/Profile-devices/operation/LinkAClientDeviceByClientId

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

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_DEVICE_CLIENT_UPDATE

User role permission required: client_info: update

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-LinkaClientdeviceRequest-apiv4

FieldTypeRequiredDescription
deviceIdstringrequiredUnique Android or iOS device ID
registrationIdstringrequiredRegistration ID for Firebase Cloud Messaging
typeenum<"android", "ios", "windows">requiredDevice type
bluetoothAddressstringoptionalBluetooth MAC address of the device
macAddressstringoptionalMAC address of the network adapter
manufacturerstringoptionalManufacturer of the device
modelstringoptionalModel of the device
osVersionstringoptionalOperating system of the device
productstringoptionalAdditional information about the OS on the device
screenHeightintegeroptionalScreen height in pixels
screenWidthintegeroptionalScreen width in pixels
publicKeystringoptionalPublic key used to encrypt push messages

Responses

StatusDescription
200Request accepted
400 application/jsonBad request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404Profile not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients/434428563/linked-devices \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"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"}'

POST /v4/clients/{identifierType}/{identifierValue}/linked-devices — Link a device by other parameters

/api-reference/profile-management#tag/Profile-devices/operation/LinkAClientDeviceByClientUuid

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

API consumers: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_BY_IDENTIFY_DEVICE_CLIENT_UPDATE

User role permission required: client_info: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"by-customId", "by-uuid">requiredThe profile identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier. It must be URL-encoded. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Acceptheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-LinkaClientdeviceRequest-apiv4

FieldTypeRequiredDescription
deviceIdstringrequiredUnique Android or iOS device ID
registrationIdstringrequiredRegistration ID for Firebase Cloud Messaging
typeenum<"android", "ios", "windows">requiredDevice type
bluetoothAddressstringoptionalBluetooth MAC address of the device
macAddressstringoptionalMAC address of the network adapter
manufacturerstringoptionalManufacturer of the device
modelstringoptionalModel of the device
osVersionstringoptionalOperating system of the device
productstringoptionalAdditional information about the OS on the device
screenHeightintegeroptionalScreen height in pixels
screenWidthintegeroptionalScreen width in pixels
publicKeystringoptionalPublic key used to encrypt push messages

Responses

StatusDescription
200Request accepted
400 application/jsonBad request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404Profile not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients/%7BidentifierType%7D/%7BidentifierValue%7D/linked-devices \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"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"}'

POST /v4/my-account/linked-devices — Link a device to currently logged in profile

/api-reference/profile-management#tag/Profile-devices/operation/LinkAClientDeviceToCurrentlyLoggedInClient

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

API consumer: Profile (Client)

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-LinkaClientdeviceRequest-apiv4

FieldTypeRequiredDescription
deviceIdstringrequiredUnique Android or iOS device ID
registrationIdstringrequiredRegistration ID for Firebase Cloud Messaging
typeenum<"android", "ios", "windows">requiredDevice type
bluetoothAddressstringoptionalBluetooth MAC address of the device
macAddressstringoptionalMAC address of the network adapter
manufacturerstringoptionalManufacturer of the device
modelstringoptionalModel of the device
osVersionstringoptionalOperating system of the device
productstringoptionalAdditional information about the OS on the device
screenHeightintegeroptionalScreen height in pixels
screenWidthintegeroptionalScreen width in pixels
publicKeystringoptionalPublic key used to encrypt push messages

Responses

StatusDescription
200Request accepted
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/my-account/linked-devices \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"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"}'

POST /push-devices/web-push/clean-up/{clientId} — Clean up web push tokens

/api-reference/profile-management#tag/Profile-devices/operation/cleanUpWebPushSubscriber

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: Synerise User, Workspace (Business Profile)

API key permission required: PUSH_DEVICES_SERVICE_WEB_PUSH_DEVICES_DELETE

User role permission required: client_detail: delete

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredUnique identifier of a profile

Request body (required)

application/json · push-devices-service-WebPushCleanupRequest

FieldTypeRequiredDescription
typeenum<"BY_UPDATED_BEFORE">required
updatedstringrequiredTokens updated before this date will be deleted.
versionstringrequiredTokens with this service worker version will be deleted.

Responses

StatusDescription
200Tokens deleted
4xx application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/push-devices/web-push/clean-up/%7BclientId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"type":"BY_UPDATED_BEFORE","updated":"2019-08-24T14:15:22Z"}'

POST /push-devices/mobile-push-subscriber/clean-up/{clientId} — Clean up mobile push tokens

/api-reference/profile-management#tag/Profile-devices/operation/cleanUpMobilePushSubscriber

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: Synerise User, Workspace (Business Profile)

API key permission required: PUSH_DEVICES_SERVICE_MOBILE_PUSH_DEVICES_DELETE

User role permission required: client_detail: delete

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredUnique identifier of a profile

Request body (required)

application/json · push-devices-service-MobilePushCleanupRequest

FieldTypeRequiredDescription
typeenum<"BY_UPDATED_BEFORE">required
updatedstringrequiredTokens updated before this date will be deleted.

Responses

StatusDescription
200Tokens deleted
4xx application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/push-devices/mobile-push-subscriber/clean-up/%7BclientId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"type":"BY_UPDATED_BEFORE","updated":"2019-08-24T14:15:22Z"}'

POST /push-devices/clients/by-uuid/{identifierValue}/linked-devices — Link a device by other parameters

/api-reference/profile-management#tag/Profile-devices/operation/LinkAClientDeviceByClientUuid

Assign a device to a profile UUID. A profile may have many devices assigned. If request is made by PROFILE or ANONYMOUS_PROFILE uuid is taken from jwt token.

API consumers: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_BY_IDENTIFY_DEVICE_CLIENT_UPDATE

User role permission required: client_info: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"by-customId", "by-uuid">requiredThe profile identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier
Acceptheaderenum<"application/json">required

Request body (required)

application/json · push-devices-service-LinkaClientdeviceRequest

FieldTypeRequiredDescription
deviceIdstringrequiredUnique Android or iOS device ID
registrationIdstringrequiredRegistration ID for Firebase Cloud Messaging
typeenum<"android", "ios", "windows">requiredDevice type
bluetoothAddressstringoptionalBluetooth MAC address of the device
macAddressstringoptionalMAC address of the network adapter
manufacturerstringoptionalManufacturer of the device
modelstringoptionalModel of the device
osVersionstringoptionalOperating system of the device
productstringoptionalAdditional information about the OS on the device
screenHeightintegeroptionalScreen height in pixels
screenWidthintegeroptionalScreen width in pixels
publicKeystringoptionalPublic key used to encrypt push messages

Responses

StatusDescription
202Request accepted
400 application/jsonBad request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404Profile not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/push-devices/clients/by-uuid/%7BidentifierValue%7D/linked-devices \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"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"}'

POST /push-devices/clients/linked-devices — Link a device by other parameters

/api-reference/profile-management#tag/Profile-devices/operation/LinkAClientDeviceByClientUuidFromJwtToken

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

API consumers: Profile (Client), Anonymous Profile

User role permission required: client_info: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"by-customId", "by-uuid">requiredThe profile identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier
Acceptheaderenum<"application/json">required

Request body (required)

application/json · push-devices-service-LinkaClientdeviceRequest

FieldTypeRequiredDescription
deviceIdstringrequiredUnique Android or iOS device ID
registrationIdstringrequiredRegistration ID for Firebase Cloud Messaging
typeenum<"android", "ios", "windows">requiredDevice type
bluetoothAddressstringoptionalBluetooth MAC address of the device
macAddressstringoptionalMAC address of the network adapter
manufacturerstringoptionalManufacturer of the device
modelstringoptionalModel of the device
osVersionstringoptionalOperating system of the device
productstringoptionalAdditional information about the OS on the device
screenHeightintegeroptionalScreen height in pixels
screenWidthintegeroptionalScreen width in pixels
publicKeystringoptionalPublic key used to encrypt push messages

Responses

StatusDescription
202Request accepted
400 application/jsonBad request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404Profile not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/push-devices/clients/linked-devices \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"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"}'

Tags

GET /v4/clients/tags — Get all tags

/api-reference/data-management#tag/Tags/operation/GetAllTags

Retrieve all tags that can be assigned to profiles.

This endpoint is available from version 4.1.0

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: API_TAGS_CLIENT_READ

User role permission required: client_tags: read

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
200 application/jsonA list of tags
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)

Example request (cURL)

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

POST /v4/tags — Create a tag

/api-reference/data-management#tag/Tags/operation/createTagUsingPOST

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: Workspace (Business Profile), Synerise User

API key permission required: API_TAGS_CREATE

User role permission required: client_tags: create

Request body

application/json · api-service-TagCreate-apiv4

FieldTypeRequiredDescription
namestringrequiredName of the tag
colorstringoptionalDisplay color of the tag; hexadecimal value

Responses

StatusDescription
200 application/jsonTag created
400 application/jsonInvalid or incomplete data
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/tags \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"nice tag","color":"#0768ff"}'

PUT /v4/tags/{tagID} — Update a tag

/api-reference/data-management#tag/Tags/operation/updateTagPUT

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: Workspace (Business Profile), Synerise User

API key permission required: API_TAGS_CREATE

User role permission required: client_tags: create

Parameters

NameInTypeRequiredDescription
tagIDpathintegerrequiredID of the tag

Request body

application/json · api-service-TagUpdate-apiv4

FieldTypeRequiredDescription
colorstringoptionalDisplay color of the tag; hexadecimal value

Responses

StatusDescription
200 application/jsonTag updated
400 application/jsonInvalid or incomplete data
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonTag doesn't exist or it is a global tag (not related to any workspace).
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/v4/tags/645 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"color":"#0768ff"}'

DELETE /v4/tags/{tagID} — Remove a tag

/api-reference/data-management#tag/Tags/operation/deleteTagDELETE

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: Workspace (Business Profile), Synerise User

API key permission required: API_TAGS_CREATE

User role permission required: client_tags: create

Parameters

NameInTypeRequiredDescription
tagIDpathintegerrequiredID of the tag

Responses

StatusDescription
202Tag removed
400 application/jsonInvalid or incomplete data
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonTag doesn't exist, was already deleted, or is a global tag (not related to any workspace).
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/v4/tags/645 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/clients/{clientId}/tags — Get profile tags

/api-reference/data-management#tag/Tags/operation/getClientTagsUsingGET

Retrieve a list of tags assigned to a profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: API_TAGS_READ

User role permission required: client_tags: read

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.

Responses

StatusDescription
200 application/jsonOK
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/clients/434428563/tags \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /v4/clients/{clientId}/tags/{tagID} — Assign tag to profile

/api-reference/data-management#tag/Tags/operation/assignTagPOST

Assign a tag to a profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: API_ASSIGN_TAGS_EXECUTE

User role permission required: client_tags: execute

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
tagIDpathintegerrequiredID of the tag

Responses

StatusDescription
200 application/jsonTag assigned
400 application/jsonProfile not found or data malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonTag not found
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/clients/434428563/tags/645

DELETE /v4/clients/{clientId}/tags/{tagID} — Remove tag from profile

/api-reference/data-management#tag/Tags/operation/removeClientTagDELETE

API consumers: Workspace (Business Profile), Synerise User

API key permission required: API_ASSIGN_TAGS_EXECUTE

User role permission required: client_tags: execute

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
tagIDpathintegerrequiredID of the tag

Responses

StatusDescription
202Tag removed
400 application/jsonProfile not found or data malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonTag not found

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/v4/clients/434428563/tags/645

Events

POST /v4/transactions — Create a transaction

/api-reference/data-management#tag/Events/operation/CreateATransaction

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: Workspace (Business Profile)

API key permission required: API_TRANSACTION_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-CreateatransactionRequest-apiv4

FieldTypeRequiredDescription
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
discountAmountobjectoptionalHow much the total cost decreased
metadataobjectoptionalAny custom parameters.If you want to send promotionCode and quantityToRedeem, contact the Synerise support to enable it for your workspace.Include these parameters in the metadata object, so Synerise can redeem it automatically.
orderIdstringrequiredID 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.
paymentInfoobjectrequiredPayment details
productsarray<api-service-Product-apiv4>requiredA list of items in the transaction. Each item creates a product.buy event. The UUID of that event is generated from a combination of: the UUID of the transaction.charge event created by the transaction the position of the item in this array. This has an effect on updating transaction events. This means that when you update a transaction (a transaction can only be updated if it has an eventSalt and the same timestamp as the original), you must keep the original order of items in the array. Otherwise, you may accidentally overwrite a product.buy event with another item's event. The system does NOT recognize the item by SKU in this case. Example: You create a transaction with items A, B and C (in that order). You update the transaction and the items are now A, B, D, and C (in that order). Because item D took the position of C in the event, it has the same UUID as C had earlier. The event of D overwrites the event of C, and C is generated as a new event. Additionally, because events can't be deleted from the database, cancelled items remain as events in a Profile's history. You can use a custom free-form property to tag items as cancelled. This way, you can keep cancelled items in products when updating a transaction without breaking the order of items. You can also use the property to filter cancelled items out in Analytics.
recordedAtstringoptionalTime 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.
revenueobjectrequiredTransaction 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.
valueobjectrequiredIf 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.
sourceenum<"WEB_DESKTOP", "WEB_MOBILE", "MOBILE_APP", "POS", …>requiredSource of the event.
eventSaltstringoptionalWhen 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

StatusDescription
202Accepted
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
404 application/jsonProfile not found or access blocked by PII protection settings
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/transactions \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"discountAmount":{"amount":0,"currency":"USD"},"metadata":{"promotionCode":"string","quantityToRedeem":0},"orderId":"be466362-71e9-4bdd-ad11-bfacead5276b","paymentInfo":{"method":"CASH"},"products":[{"finalUnitPrice":{"amount":3.25,"currency":"USD"},"name":"Soft drink","sku":"189784563455","categories":["string"],"image":"string","url":"string","netUnitPrice":{"amount":3.25,"currency":"USD"},"tax":0.1,"quantity":2.5,"regularPrice":{"amount":3.25,"currency":"USD"},"discountPrice":{"amount":15.5,"currency":"USD"},"discountPercent":0.1,"property1":null,"property2":null}],"recordedAt":"2019-02-07T09:53:56.999+00:00","revenue":{"amount":64.25,"currency":"USD"},"value":{"amount":112.25,"currency":"USD"},"source":"MOBILE","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00"}'

POST /v4/transactions/batch — Batch add or update transactions

/api-reference/data-management#tag/Events/operation/BatchAddOrUpdateTransactions

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: Workspace (Business Profile)

API key permission required: API_BATCH_TRANSACTION_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · array<api-service-CreateatransactionRequest-apiv4>

An array of transactions to post or update

Responses

StatusDescription
202Accepted
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/transactions/batch \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"discountAmount":{"amount":0,"currency":"USD"},"metadata":{"promotionCode":"string","quantityToRedeem":0},"orderId":"be466362-71e9-4bdd-ad11-bfacead5276b","paymentInfo":{"method":"CASH"},"products":[{"finalUnitPrice":{"amount":3.25,"currency":"USD"},"name":"Soft drink","sku":"189784563455","categories":["string"],"image":"string","url":"string","netUnitPrice":{"amount":3.25,"currency":"USD"},"tax":0.1,"quantity":2.5,"regularPrice":{"amount":3.25,"currency":"USD"},"discountPrice":{"amount":15.5,"currency":"USD"},"discountPercent":0.1,"property1":null,"property2":null}],"recordedAt":"2019-02-07T09:53:56.999+00:00","revenue":{"amount":64.25,"currency":"USD"},"value":{"amount":112.25,"currency":"USD"},"source":"MOBILE","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00"}]'

GET /v4/events/by-client/{clientId} — Get Profile events as Workspace (deprecated)

/api-reference/data-management#tag/Events/operation/GetClientEvents

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

Retrieve a list of events saved in a Profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: API_LISTING_BY_CLIENT_EVENTS_READ

User role permission required: client_activities: read

Parameters

NameInTypeRequiredDescription
clientIdpathintegerrequiredThe ID of the profile Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required
time[from]querystringoptionalStart 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]querystringoptionalEnd 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.
actionquerystringoptionalFilter events by action type. For example, to retrieve completed transactions, enter transaction.charge
limitqueryintegeroptionalThe number of events to retrieve

Responses

StatusDescription
200 application/jsonA list of events
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)

Example request (cURL)

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'

GET /v4/events — Get Profile's own events (deprecated)

/api-reference/data-management#tag/Events/operation/GetClientOwnEvents

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: Profile (Client)

Parameters

NameInTypeRequiredDescription
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4">required
time[from]querystringoptionalStart 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]querystringoptionalEnd 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.
actionquerystringoptionalFilter events by action type. For example, to retrieve completed transactions, enter transaction.charge
limitqueryintegeroptionalThe number of events to retrieve

Responses

StatusDescription
200 application/jsonA list of events
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type
500 application/jsonInternal Server Error

Example request (cURL)

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'

POST /v4/events/application-started — Application started

/api-reference/data-management#tag/Events/operation/ApplicationStarted

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_APPLICATION_STARTED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-ApplicationstartedRequest-apiv4

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectrequiredAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type
500 application/jsonInternal Server Error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/application-started \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"applicationName":"string","version":"string"}}'

POST /v4/events/registered — Profile account registered

/api-reference/data-management#tag/Events/operation/ClientRegistered

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_REGISTERED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/registered \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/logged-in — Profile logged in

/api-reference/data-management#tag/Events/operation/ClientLoggedIn

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_LOGGED_IN_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/logged-in \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/logged-out — Profile logged out

/api-reference/data-management#tag/Events/operation/ClientLoggedOut

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_LOGGED_OUT_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/logged-out \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/added-to-cart — Item added to cart

/api-reference/data-management#tag/Events/operation/ClientAddedProductToCart

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_ADDED_TO_CART_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-ClientCartEventRequest-apiv4

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectrequiredAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/added-to-cart \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"sku":"189784563455","name":"Soft drink","category":"Beverages","categories":["string"],"offline":true,"source":"MOBILE","regularUnitPrice":{"amount":0,"currency":"USD"},"discountedUnitPrice":{"amount":0,"currency":"USD"},"finalUnitPrice":{"amount":3.25,"currency":"USD"},"ItemUrlAddress":"string","producer":"string","quantity":0}}'

POST /v4/events/removed-from-cart — Item removed from cart

/api-reference/data-management#tag/Events/operation/ClientRemovedProductFromCart

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_REMOVED_FROM_CART_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · api-service-ClientCartEventRequest-apiv4

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectrequiredAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/removed-from-cart \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"sku":"189784563455","name":"Soft drink","category":"Beverages","categories":["string"],"offline":true,"source":"MOBILE","regularUnitPrice":{"amount":0,"currency":"USD"},"discountedUnitPrice":{"amount":0,"currency":"USD"},"finalUnitPrice":{"amount":3.25,"currency":"USD"},"ItemUrlAddress":"string","producer":"string","quantity":0}}'

POST /v4/events/added-to-favorites — Product added to favorites

/api-reference/data-management#tag/Events/operation/ClientAddedProductToFavorites

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_ADDED_TO_FAVORITES_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/added-to-favorites \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/product-view — Item viewed

/api-reference/data-management#tag/Events/operation/ClientViewedProduct

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_PRODUCT_VIEW_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/product-view \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"productId":"189784563455","name":"Soft drink","fromRecommendation":true,"source":"MOBILE","category":"Beverages","url":"string","campaignHash":"21e0d4b0-bd4e-497b-817b-4fr660284918"}}'

POST /v4/events/assigned-to-company — Profile assigned to company

/api-reference/data-management#tag/Events/operation/ClientAssignedToCompany

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: Workspace (Business Profile), Synerise User, Profile (Client), Anonymous Profile

API key permission required: API_ASSIGNED_TO_COMPANY_EVENTS_CREATE

User role permission required: client_activities: create

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectrequiredAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/assigned-to-company \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"companyId":0}}'

POST /v4/events/appeared-in-location — Profile logged location

/api-reference/data-management#tag/Events/operation/ClientAppearedInLocation

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_APPEARED_IN_LOCATION_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/appeared-in-location \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"lat":50.021102,"lon":19.886218}}'

POST /v4/events/push/received — Push notification received

/api-reference/data-management#tag/Events/operation/ClientReceivedPushNotification

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_PUSH_RECIVED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/push/received \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/push/viewed — Push notification viewed

/api-reference/data-management#tag/Events/operation/ClientViewedPushNotification

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_PUSH_VIEWED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/push/viewed \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/push/clicked — Push notification clicked

/api-reference/data-management#tag/Events/operation/ClientClickedPushNotification

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_PUSH_CLICKED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/push/clicked \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/push/cancelled — Push notifications cancelled

/api-reference/data-management#tag/Events/operation/ClientCancelledPushNotifications

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_PUSH_CANCELLED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/push/cancelled \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/cancelled-transaction — Transaction cancelled

/api-reference/data-management#tag/Events/operation/ClientCancelledTransaction

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: Workspace (Business Profile)

API key permission required: API_CANCELLED_TRANSACTION_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/cancelled-transaction \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"orderId":"be466362-71e9-4bdd-ad11-bfacead5276b","orderStatus":"string","discountAmount":{"amount":0,"currency":"USD"},"discountPercent":0.1,"discountCode":"string","value":{"amount":112.25,"currency":"USD"},"revenue":{"amount":64.25,"currency":"USD"},"products":[{"finalUnitPrice":{"amount":3.25,"currency":"USD"},"name":"Soft drink","sku":"189784563455","categories":["string"],"image":"string","url":"string","netUnitPrice":{"amount":3.25,"currency":"USD"},"tax":0.1,"quantity":2.5,"regularPrice":{"amount":3.25,"currency":"USD"},"discountPrice":{"amount":15.5,"currency":"USD"},"discountPercent":0.1,"property1":null,"property2":null}],"source":"MOBILE","paymentInfo":{"method":"CASH"}}}'

POST /v4/events/hit-timer — Timer hit

/api-reference/data-management#tag/Events/operation/ClientHitTimer

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_HIT_TIMER_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/hit-timer \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/searched — Search requested

/api-reference/data-management#tag/Events/operation/ClientSearched

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_SEARCHED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/searched \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/shared — Content shared

/api-reference/data-management#tag/Events/operation/ClientShared

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_SHARED_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/shared \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/recommendation-seen — Recommendation viewed (deprecated)

/api-reference/data-management#tag/Events/operation/RecommendationSeen

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: Workspace (Business Profile), Profile (Client), Anonymous Profile, Web SDK Tracker, AI API key (legacy)

API key permission required: API_RECOMENDATION_SEEN_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/recommendation-seen \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"productId":"189784563455","name":"Soft drink","source":"MOBILE","campaignHash":"21e0d4b0-bd4e-497b-817b-4fr660284918","url":"string","category":"Beverages"}}'

POST /v4/events/recommendation-click — Recommendation clicked (deprecated)

/api-reference/data-management#tag/Events/operation/RecommendationClicked

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: Workspace (Business Profile), Profile (Client), Anonymous Profile, Web SDK Tracker, AI API key (legacy)

API key permission required: API_RECOMMENDATION_CLICK_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/recommendation-click \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{"productId":"189784563455","name":"Soft drink","source":"MOBILE","campaignHash":"21e0d4b0-bd4e-497b-817b-4fr660284918","url":"string","category":"Beverages"}}'

POST /v4/events/visited-screen — Mobile app screen visited

/api-reference/data-management#tag/Events/operation/ClientVisitedScreen

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_VISITED_SCREEN_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/visited-screen \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","params":{}}'

POST /v4/events/custom — Custom event

/api-reference/data-management#tag/Events/operation/CustomEvent

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: Workspace (Business Profile), Profile (Client), Anonymous Profile, Synerise User

API key permission required: API_CUSTOM_EVENTS_CREATE

User role permission required: client_activities: create

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · object

FieldTypeRequiredDescription
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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.
actionstringrequiredFor 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\\.\\-_]{2,64}$
paramsobjectoptionalAdditional 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

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/custom \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","action":"context.action","params":{}}'

POST /v4/events/batch — Batch send events

/api-reference/data-management#tag/Events/operation/BatchSendEvents

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: Workspace (Business Profile), Profile (Client), Anonymous Profile

API key permission required: API_BATCH_EVENTS_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body (required)

application/json · array<any>

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.

Responses

StatusDescription
202Accepted
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/batch \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00","type":"string","action":"context.action","params":{}}]'

GET /v4/server/time — Get server time

/api-reference/data-management#tag/Events/operation/getServerTime

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

API consumers: Workspace (Business Profile), Profile (Client), Anonymous Profile

Authentication: Not required

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Responses

StatusDescription
200 application/jsonOK
400 application/jsonBad Request
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)

Example request (cURL)

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

POST /v4/events/recommendation-view — Recommendation viewed

/api-reference/data-management#tag/Events/operation/publishRecommendationViewEventUsingPOST

A recommendation was displayed to a customer.

API consumers: Workspace (Business Profile), Profile (Client), Anonymous Profile, Web SDK Tracker, AI API key (legacy)

API key permission required: API_RECOMMENDATION_VIEW_EVENT_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · api-service-RecommendationViewEventData-apiv4

FieldTypeRequiredDescription
paramsobjectrequiredAdditional 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
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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

StatusDescription
200OK
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/recommendation-view \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"params":{"items":["string"],"correlationId":"string","campaignId":"string"},"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00"}'

POST /v4/events/item-search-click — Search result clicked

/api-reference/data-management#tag/Events/operation/publishItemSearchClickEventUsingPOST

An item in a search result was clicked or tapped.

API consumers: Workspace (Business Profile), Profile (Client), Anonymous Profile, Web SDK Tracker, AI API key (legacy)

API key permission required: API_ITEM_SEARCH_CLICK_EVENT_CREATE

Parameters

NameInTypeRequiredDescription
Api-Versionheaderenum<"4.4">required

Request body

application/json · api-service-ItemSearchClickEventData-apiv4

FieldTypeRequiredDescription
paramsobjectrequiredAdditional 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
labelstringrequiredThis parameter is required, but not saved in the database. It can't be used in Analytics, Automations, and so on.
clientobjectrequiredYou must provide at least one of those profile identifiers. Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to identifier and UUID handling.
timestringoptionalTime 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.
eventSaltstringoptionalWhen 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

StatusDescription
200OK
400 application/jsonBad request: input data missing or malformed
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
415 application/jsonUnsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/item-search-click \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"params":{"item":"string","correlationId":"string","position":0,"searchType":"full-text-search"},"label":"Human-readable label","client":{"customId":"string","id":433230297,"uuid":"07243772-008a-42e1-ba37-c3807cebde8f","email":"string"},"time":"2019-02-07T09:53:56.999+00:00","eventSalt":"972346context.action2019-02-07T09:53:56.999+00:00"}'

Back to all API categories