Data Management — API Reference

Gather and manage data from all of your touchpoints and use it in our Analytics Suite or retrieve it for use in other services.

139 endpoints across 9 tags.

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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · api-service-CreateatransactionRequest-apiv4

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile not found or access blocked by PII protection settings
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

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

An array of transactions to post or update

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	The 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-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required
`time[from]`	query	string	optional	Start of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the results are returned starting with the oldest entry in the database.
`time[to]`	query	string	optional	End of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the current time applies.
`action`	query	string	optional	Filter events by action type. For example, to retrieve completed transactions, enter `transaction.charge`
`limit`	query	integer	optional	The number of events to retrieve

Responses

Status	Description
`200` `application/json`	A list of events
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; 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

Name	In	Type	Required	Description
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required
`time[from]`	query	string	optional	Start of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the results are returned starting with the oldest entry in the database.
`time[to]`	query	string	optional	End of the time range to query. UTC time in ISO 8601 (for example, `2020-10-19T13:47:53Z`). If no value is provided, the current time applies.
`action`	query	string	optional	Filter events by action type. For example, to retrieve completed transactions, enter `transaction.charge`
`limit`	query	integer	optional	The number of events to retrieve

Responses

Status	Description
`200` `application/json`	A list of events
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type
`500` `application/json`	Internal 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · api-service-ApplicationstartedRequest-apiv4

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type
`500` `application/json`	Internal 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · api-service-ClientCartEventRequest-apiv4

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · api-service-ClientCartEventRequest-apiv4

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body (required)

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · object

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

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"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

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`200` `application/json`	OK
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · api-service-RecommendationViewEventData-apiv4

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

Responses

Status	Description
`200`	OK
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"4.4">	required

Request body

application/json · api-service-ItemSearchClickEventData-apiv4

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

Responses

Status	Description
`200`	OK
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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"}'

AI Events

`POST` `/v4/events/ai-compat/batch` — Batch upload AI events

/api-reference/data-management#tag/AI-Events/operation/publishAiCompatBatchUsingPOST

Upload a batch of events to the AI engine. A request can only include events of one type.

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

API key permission required: API_BATCH_EVENTS_CREATE

Request body

application/json · api-service-AiCompatBatchEventRequest-apiv4

Field	Type	Required	Description
`eventType`	enum<"item.search.click", "suggestion.search.click", "product.search.click", "recommendation.click", …>	optional	A request can only include events of the same type.
`items`	array<any>	optional	An array of events

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/ai-compat/batch \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"eventType":"item.search.click","items":[{"correlationId":"string","clientUUID":"07243772-008a-42e1-ba37-c3807cebde8f","position":0,"searchType":"full-text-search","item":"string","EventTimestamp":"2019-02-07T09:53:56.999+00:00","property1":null,"property2":null}]}'

`POST` `/v4/events/ai-compat/item.search.click` — Item clicked in search

/api-reference/data-management#tag/AI-Events/operation/publishAiCompatItemSearchClickUsingPOST

Upload an item.search.click event to the AI engine.

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

Request body

application/json · api-service-ItemSearchClickEventDataCompat-apiv4

Field	Type	Required	Description
`correlationId`	string	required	`correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
`clientUUID`	string	required	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`position`	integer	required	Position of the clicked item in the result list (count starts with 1)
`searchType`	enum<"full-text-search", "autocomplete", "listing", "visual">	required	Type of the search
`item`	string	required	itemId (also called `sku`, `productId`, and `retailer_part_no` in other APIs and SDKs) of the item
`EventTimestamp`	string	optional	Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition.For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.

Responses

Status	Description
`204`	No Content
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/ai-compat/item.search.click \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"correlationId":"string","clientUUID":"07243772-008a-42e1-ba37-c3807cebde8f","position":0,"searchType":"full-text-search","item":"string","EventTimestamp":"2019-02-07T09:53:56.999+00:00","property1":null,"property2":null}'

`POST` `/v4/events/ai-compat/suggestion.search.click` — Suggestion clicked in search

/api-reference/data-management#tag/AI-Events/operation/publishAiCompatSuggestionSearchClickUsingPOST

Upload a suggestion.search.click event to the AI engine.

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

API key permission required: API_SUGGESTION_SEARCH_CLICK_EVENT_CREATE

Request body

application/json · api-service-SuggestionSearchClickEventDataCompat-apiv4

Field	Type	Required	Description
`correlationId`	string	required	`correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
`clientUUID`	string	required	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`position`	integer	required	Position of the clicked item in the result list (count starts with 1)
`searchType`	enum<"full-text-search", "autocomplete", "listing", "visual">	required	Type of the search
`EventTimestamp`	string	optional	Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition.For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
`suggestion`	string	required	Suggestion name

Responses

Status	Description
`204`	No Content
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/ai-compat/suggestion.search.click \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"correlationId":"string","clientUUID":"07243772-008a-42e1-ba37-c3807cebde8f","position":0,"searchType":"full-text-search","EventTimestamp":"2019-02-07T09:53:56.999+00:00","suggestion":"string","property1":null,"property2":null}'

`POST` `/v4/events/ai-compat/product.search.click` — Product clicked in search (deprecated)

/api-reference/data-management#tag/AI-Events/operation/publishAiCompatProductSearchClickUsingPOST

Upload a product.search.click event to the AI engine.

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

API key permission required: API_PRODUCT_SEARCH_CLICK_EVENT_CREATE

Request body

application/json · api-service-ProductSearchClickEventDataCompat-apiv4

Field	Type	Required	Description
`correlationId`	string	required	`correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
`clientUUID`	string	required	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`position`	integer	required	Position of the clicked item in the result list (count starts with 1)
`searchType`	enum<"full-text-search", "autocomplete", "listing", "visual">	required	Type of the search
`productId`	string	required	itemId (also called `sku`, `productId`, and `retailer_part_no` in other APIs and SDKs) of the item
`EventTimestamp`	string	optional	Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition.For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.

Responses

Status	Description
`202`	Accepted
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/ai-compat/product.search.click \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"correlationId":"string","clientUUID":"07243772-008a-42e1-ba37-c3807cebde8f","position":0,"searchType":"full-text-search","productId":"string","EventTimestamp":"2019-02-07T09:53:56.999+00:00","property1":null,"property2":null}'

`POST` `/v4/events/ai-compat/recommendation.click` — Item clicked in recommendation

/api-reference/data-management#tag/AI-Events/operation/publishAiCompatRecommendationClickUsingPOST

Upload a recommendation.click event to the AI engine.

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

API key permission required: API_RECOMMENDATION_CLICK_EVENT_CREATE

Request body

application/json · api-service-RecommendationClickEventDataCompat-apiv4

Field	Type	Required	Description
`correlationId`	string	required	`correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
`clientUUID`	string	required	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`item`	string	required	itemId (also called `sku`, `productId`, and `retailer_part_no` in other APIs and SDKs) of the item
`campaignId`	string	optional	ID of the campaign related to the event
`sessionId`	string	optional	ID of the user session
`EventTimestamp`	string	optional	Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition.For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.

Responses

Status	Description
`204`	No Content
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/ai-compat/recommendation.click \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"correlationId":"string","clientUUID":"07243772-008a-42e1-ba37-c3807cebde8f","item":"string","campaignId":"string","sessionId":"string","EventTimestamp":"2019-02-07T09:53:56.999+00:00","property1":null,"property2":null}'

`POST` `/v4/events/ai-compat/recommendation.view` — Recommendation viewed

/api-reference/data-management#tag/AI-Events/operation/publishAiCompatRecommendationViewUsingPOST

Upload a recommendation.view event to the AI engine.

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

Request body

application/json · api-service-RecommendationViewEventDataCompat-apiv4

Field	Type	Required	Description
`correlationId`	string	required	`correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
`clientUUID`	string	required	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`items`	array<api-service-Item-apiv4>	required	An array of items included in the recommendation. The items are identified by their `itemId` (also called `sku`, `productId`, and `retailer_part_no` in other APIs and SDKs)
`EventTimestamp`	string	optional	Time when the event occurred, in ISO 8601. This time isn't affected and doesn't affect the timezone of your workspace - you can send events with a timezone different than that of the workspace. Synerise calculates the times into UTC standard when saving events in the database. If not defined, the backend inserts the time of receiving the event. A time with a "Z" at the end (for example, `2022-10-14T12:02:06Z`) denotes a time in the UTC standard. If you want to send time in a different timezone, you can do this by appending `{+\|-}hh:mm` at the end of the string. Note that if the timezone is ahead (+) of UTC, the UTC time is calculated by subtraction. When the timezone is behind (-) UTC, the UTC time is calculated by addition.For example: if your timezone is UTC+1, append `+01:00`. When you send `2022-10-14T15:00:000+01:00`, it is saved in the database as `2022-10-14T14:00:000Z` if your timezone is UTC-8, append `-08:00`. When you send `2022-10-14T22:00:000-08:00`, it is saved in the database as `2022-10-15T06:00:000Z` (note that the date also changes between timezones in this example) IMPORTANT: If you send an event with a future time, the parameter is rejected and the time of receiving the event is saved as the occurrence time. For example, if your timezone is UTC+1 and you send the event at 15:00 local time, future times are: later than 15:00 local time later than 14:00 UTC When you retrieve an event, its time is always shown as UTC. The original time string that you sent (even if it was a future time and was rejected) can be retrieved with the activities endpoints, as `snr-original-time`.
`campaignId`	string	optional	ID of the campaign related to the event

Responses

Status	Description
`204`	No Content
`400` `application/json`	Bad request: input data missing or malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/events/ai-compat/recommendation.view \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"correlationId":"string","clientUUID":"07243772-008a-42e1-ba37-c3807cebde8f","items":["string"],"EventTimestamp":"2019-02-07T09:53:56.999+00:00","campaignId":"string","property1":null,"property2":null}'

Activities

`GET` `/activities-api/activities/{clientId}` — Get profile activities (deprecated)

/api-reference/data-management#tag/Activities/operation/getActivitiesPerClient

Retrieve a list of activities from a single profile.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_READ

User role permission required: client_activities: read

Parameters

Name	In	Type	Required	Description
`clientId`	path	number	required	The ID of the profile
`dateFrom`	query	number	optional	Lower value of the time range, as a Unix timestamp in milliseconds. Defaults to current time minus 2 hours.
`dateTo`	query	number	optional	Upper limit of the time range to fetch, as a Unix timestamp in milliseconds. Defaults to current time.
`actions`	query	string	optional	A comma-separated list of actions (or a single action) that will be included in the response
`limit`	query	number	optional	The maximum number of events to retrieve
`raw`	query	boolean	optional	When `true`, the response returns raw data. If raw data is not available, processed data from event storage (like from `"raw": false`) is returned instead.
`format`	query	enum<"json", "csv">	optional	The format of the retrieved data

Responses

Status	Description
`200` `application/json`	Activities

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/activities-api/activities/434428563?dateFrom=SOME_NUMBER_VALUE&dateTo=SOME_NUMBER_VALUE&actions=page.visit&limit=SOME_NUMBER_VALUE&raw=SOME_BOOLEAN_VALUE&format=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/activities-api/activity/by/{identifierType}` — Get a single activity (deprecated)

/api-reference/data-management#tag/Activities/operation/getActivityForClient

Retrieve the details of a single activity.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_READ

User role permission required: client_activities: read

Parameters

Name	In	Type	Required	Description
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type

Request body

application/json · activities-api-SingleActivityRequest

Field	Type	Required	Description
`identifierValue`	string	required	Value of the selected profile identifier
`additionalData`		required	Identification of the event to retrieve

Responses

Status	Description
`200` `application/json`	Activity

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activities-api/activity/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string","additionalData":{"time":"1667563770404","unique":"1245924049"}}'

`GET` `/activities-api/descriptions` — Get description mappings

/api-reference/data-management#tag/Activities/operation/getDescription

Retrieve a list of existing event-description mappings

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_READ

User role permission required: client_activities: read

Responses

Status	Description
`200` `application/json`	Description mappings

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/activities-api/descriptions \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/activities-api/descriptions` — Add description mapping

/api-reference/data-management#tag/Activities/operation/addDescription

For each event, you can add a custom, human-readable description that's displayed in the Synerise Web Application

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_UPDATE

User role permission required: client_activities: update

Request body (required)

application/json · activities-api-descriptionRequest

Details of the description mapping

Field	Type	Required	Description
`action`	string	optional	Action name. Can be up to 32 characters long and must match the following regular expression: `^[a-zA-Z0-9\.\-_]+$`
`description`	string	optional	Event description shown in a Profile card. Can include jinja inserts, which are returned unprocessed. This description is not used when searching for events in Analytics or for Automation trigger purposes.

Responses

Status	Description
`200` `application/json`	Description mapping

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activities-api/descriptions \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"page.visit","description":"string"}'

`POST` `/activities-api/descriptions/{descriptionId}` — Update description mapping

/api-reference/data-management#tag/Activities/operation/updateDescriptionsById

Modify an existing description mapping

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_UPDATE

User role permission required: client_activities: update

Parameters

Name	In	Type	Required	Description
`descriptionId`	path	number	required	ID of the mapping

Request body (required)

application/json · activities-api-descriptionRequest

Updated information

Field	Type	Required	Description
`action`	string	optional	Action name. Can be up to 32 characters long and must match the following regular expression: `^[a-zA-Z0-9\.\-_]+$`
`description`	string	optional	Event description shown in a Profile card. Can include jinja inserts, which are returned unprocessed. This description is not used when searching for events in Analytics or for Automation trigger purposes.

Responses

Status	Description
`200` `application/json`	Description mapping

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activities-api/descriptions/%7BdescriptionId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"page.visit","description":"string"}'

`GET` `/activities-api/labels` — Get label mappings

/api-reference/data-management#tag/Activities/operation/getLabel

Retrieve a list of existing event-label mappings

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_READ

User role permission required: client_activities: read

Responses

Status	Description
`200` `application/json`	Label mappings

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/activities-api/labels \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/activities-api/labels` — Add label mapping

/api-reference/data-management#tag/Activities/operation/addLabel

For each event, you can add a custom, human-readable label that's displayed in the Synerise Web Application

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_UPDATE

User role permission required: client_activities: update

Request body (required)

application/json · activities-api-labelRequest

Details of the label mapping

Field	Type	Required	Description
`action`	string	optional	Action name. Can be up to 32 characters long and must match the following regular expression: `^[a-zA-Z0-9\.\-_]+$`
`label`	string	optional	Event name shown in a Profile card. Can include jinja inserts, which are returned unprocessed. This description is not used when searching for events in Analytics or for Automation trigger purposes.

Responses

Status	Description
`200` `application/json`	Label mapping

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activities-api/labels \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"page.visit","label":"string"}'

`POST` `/activities-api/labels/{labelId}` — Update label mapping

/api-reference/data-management#tag/Activities/operation/updateLabelById

Modify an existing label mapping

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_UPDATE

User role permission required: client_activities: update

Parameters

Name	In	Type	Required	Description
`labelId`	path	number	required	ID of the mapping

Request body (required)

application/json · activities-api-labelRequest

Updated information

Field	Type	Required	Description
`action`	string	optional	Action name. Can be up to 32 characters long and must match the following regular expression: `^[a-zA-Z0-9\.\-_]+$`
`label`	string	optional	Event name shown in a Profile card. Can include jinja inserts, which are returned unprocessed. This description is not used when searching for events in Analytics or for Automation trigger purposes.

Responses

Status	Description
`200` `application/json`	Label mapping

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activities-api/labels/%7BlabelId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"page.visit","label":"string"}'

`GET` `/activities-api/icons` — Get icon mappings

/api-reference/data-management#tag/Activities/operation/getIcons

Retrieve a list of existing event-icon mappings

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_READ

User role permission required: client_activities: read

Responses

Status	Description
`200` `application/json`	Icon mappings

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/activities-api/icons \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/activities-api/icons` — Add icon mapping

/api-reference/data-management#tag/Activities/operation/addIcon

For each event, you can add a custom icon that's displayed in the Synerise Web Application

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_UPDATE

User role permission required: client_activities: update

Request body (required)

application/json · activities-api-iconRequest

Icon details

Field	Type	Required	Description
`action`	string	required	Action name. Can be up to 32 characters long and must match the following regular expression: `^[a-zA-Z0-9\.\-_]+$`
`icons`	object	required	Icon configuration with primary, secondary icon and color

Responses

Status	Description
`200` `application/json`	Icon

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activities-api/icons \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"page.visit","icons":{"primary":"string","secondary":"string","color":"string"}}'

`POST` `/activities-api/icons/{iconID}` — Update icon mapping

/api-reference/data-management#tag/Activities/operation/updateIconById

Modify an existing icon mapping

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ACTIVITIES_API_ACTIVITIES_UPDATE

User role permission required: client_activities: update

Parameters

Name	In	Type	Required	Description
`iconID`	path	number	required	ID of the icon

Request body (required)

application/json · activities-api-iconRequest

Updated mapping data

Field	Type	Required	Description
`action`	string	required	Action name. Can be up to 32 characters long and must match the following regular expression: `^[a-zA-Z0-9\.\-_]+$`
`icons`	object	required	Icon configuration with primary, secondary icon and color

Responses

Status	Description
`200` `application/json`	Icon mapping

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activities-api/icons/%7BiconID%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"page.visit","icons":{"primary":"string","secondary":"string","color":"string"}}'

`GET` `/activities-api/events` — Get profile's own events

/api-reference/data-management#tag/Activities/operation/getEvents

As a profile, retrieve a list of your own events.

API consumer: Profile (Client)

User role permission required: client_activities: read

Parameters

Name	In	Type	Required	Description
`actions`	query	string	optional	A comma-separated list of actions (or a single action) that will be included in the response
`dateFrom`	query	number	optional	Lower value of the time range, as a Unix timestamp in milliseconds.
`dateTo`	query	number	optional	Upper limit of the time range to fetch, as a Unix timestamp in milliseconds.
`limit`	query	number	optional	The maximum number of events to retrieve
`raw`	query	boolean	optional	When `true`, the response returns raw data. If raw data is not available, processed data from event storage (like from `"raw": false`) is returned instead.
`pageToken`	query	string	optional	The token of the page to retrieve. You can check the tokens of the next/previous page in the response to this endpoint. If not provided, the first page is retrieved.
`sortBy`	query	enum<"time:desc", "time:asc">	optional	Sorting order. `time:desc` (default) returns newest events first.

Responses

Status	Description
`200` `application/json`	Events

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/activities-api/events?actions=page.visit&dateFrom=SOME_NUMBER_VALUE&dateTo=SOME_NUMBER_VALUE&limit=SOME_NUMBER_VALUE&raw=SOME_BOOLEAN_VALUE&pageToken=SOME_STRING_VALUE&sortBy=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/activities-api/events/by/{identifierType}` — Get profile events as a workspace/Synerise user

/api-reference/data-management#tag/Activities/operation/getEventsByIdentifier

Retrieve a list of events for the single profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ACTIVITIES_API_ACTIVITIES_READ

User role permission required: client_activities: read

Parameters

Name	In	Type	Required	Description
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type
`pageToken`	query	string	optional	The token of the page to retrieve. You can check the tokens of the next/previous page in the response to this endpoint. If not provided, the first page is retrieved.

Request body

application/json · activities-api-ClientEventsRequest

Field	Type	Required	Description
`identifierValue`	string	required	Value of the identifier selected in `identifierType`
`additionalData`	object	required	Pagination, date filters, and other optional parameters

Responses

Status	Description
`200` `application/json`	Events

Example request (cURL)

curl --request POST \
  --url 'https://api.synerise.com/activities-api/events/by/%7BidentifierType%7D?pageToken=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string","additionalData":{"actions":"page.visit,client.login","dateFrom":"1720688755000","dateTo":"1720695955000","limit":50,"raw":"true","pageToken":"string","sortBy":"time:desc"}}'

Catalogs

`GET` `/catalogs/bags/{catalogId}/csv` — Get all items as CSV file

/api-reference/data-management#tag/Catalogs/operation/getItemsCSV

Download a CSV with all items in the catalog. The unique identifier of an item is saved in the item_key column.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog
`delimiter`	query	string	optional	The delimiter to use in csv. You can use `;` or `,`. Default: `,`

Responses

Status	Description
`200` `text/csv`	CSV file. The unique identifier of an item is in the `item_key` column.
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/csv?delimiter=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/catalogs/bags/{catalogId}/items/upload` — Add items from CSV

/api-reference/data-management#tag/Catalogs/operation/uploadItems

Upload items to a catalog from a CSV file

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_UPDATE

User role permission required: assets_catalogs: update

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body

multipart/form-data · object

Field	Type	Required	Description
`itemKey`	string	required	The name of the CSV column that contains unique identifiers. Slashes (`/`) are not allowed in the identifier values.
`file`	string	required	CSV file

Responses

Status	Description
`200` `application/json`	Upload status
`400` `text/plain`	Invalid or insufficient data
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items/upload \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: multipart/form-data' \
  --form itemKey=string \
  --form file=string

`GET` `/catalogs/bags` — Get catalogs

/api-reference/data-management#tag/Catalogs/operation/getBags

Retrieve all catalogs from the Workspace. You can filter and sort the results.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`searchBy`	query	string	optional	A search string. You can search the catalogs by their name or the first or last name of the author.
`orderBy`	query	enum<"id", "author", "lastModified", "creationDate">	optional	The parameter to order the results by. Order is always ascending.
`offset`	query	integer	optional	The offset for the search. For example, if your `limit` is 10 and you want to retrieve the third page of items, set the offset to 20. Items with indexes 20 to 29 are returned (the first item on the first page has the index 0).
`limit`	query	integer	optional	The maximum number of items to include in the response. `offset` must be defined. Default: 100

Responses

Status	Description
`200` `application/json`	List of catalogs
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/catalogs/bags?searchBy=SOME_STRING_VALUE&orderBy=SOME_STRING_VALUE&offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/catalogs/bags` — Add catalog

/api-reference/data-management#tag/Catalogs/operation/addBag

Create a new, empty catalog.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_CREATE

User role permission required: assets_catalogs: create

Request body (required)

application/json · catalogs-addBag

Field	Type	Required	Description
`name`	string	optional	Catalog name

Responses

Status	Description
`200` `application/json`	Details of the created catalog
`400` `text/plain`	Invalid or insufficient data
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/bags \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string"}'

`DELETE` `/catalogs/bags` — Delete catalogs

/api-reference/data-management#tag/Catalogs/operation/deleteBagByIds

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_DELETE

User role permission required: assets_catalogs: delete

Request body (required)

application/json · array<string>

Responses

Status	Description
`200` `application/json`	Deletion status
`400` `text/plain`	Invalid or insufficient data
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/catalogs/bags \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[1199,1200,1201]'

`GET` `/catalogs/bags/{catalogId}/keys` — Get catalog keys

/api-reference/data-management#tag/Catalogs/operation/getKeysByBag

Retrieve the list of keys from a catalog.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Responses

Status	Description
`200` `application/json`	List of keys
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/keys \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`GET` `/catalogs/bags/{catalogId}` — Get catalog info

/api-reference/data-management#tag/Catalogs/operation/getBagById

Retrieve the metadata of a catalog

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Responses

Status	Description
`200` `application/json`	Details of the catalog
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`DELETE` `/catalogs/bags/{catalogId}` — Delete catalog

/api-reference/data-management#tag/Catalogs/operation/deleteBagById

Delete a single catalog. This operation is irreversible.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_DELETE

User role permission required: assets_catalogs: delete

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Responses

Status	Description
`200` `application/json`	Deletion status
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`GET` `/catalogs/bags/{catalogId}/items` — Get items from catalog

/api-reference/data-management#tag/Catalogs/operation/getItemsByBag

Retrieve the entries from a single catalog.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog
`itemKey`	query	string	optional	Filter by the value of the unique identifier of the item (exact match)
`offset`	query	integer	optional	The offset for the search. For example, if your `limit` is 10 and you want to retrieve the third page of items, set the offset to 20. Items with indexes 20 to 29 are returned (the first item on the first page has the index 0).
`limit`	query	integer	optional	The maximum number of items to include in the response. `offset` must be defined. Default: 100

Responses

Status	Description
`200` `application/json`	A list of items in the catalog

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items?itemKey=SOME_STRING_VALUE&offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/catalogs/bags/{catalogId}/items` — Add item

/api-reference/data-management#tag/Catalogs/operation/addItems

Add a single item to the catalog.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_ITEM_BATCH_CATALOG_CREATE

User role permission required: assets_catalogs: create

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body (required)

application/json · catalogs-addItem

JSON object with any number of key/value pairs

Field	Type	Required	Description
`itemKey`	string	required	The value of the unique key of the item. Slashes (`/`) are not allowed in the value. In the Synerise Portal, this value is saved under Primary key.
`value`	object	required	Properties of the item. Can be an empty object.

Responses

Status	Description
`200` `application/json`	Upload status
`400` `text/plain`	Invalid or insufficient data
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}'

`POST` `/catalogs/bags/{catalogId}/items/batch` — Batch add items

/api-reference/data-management#tag/Catalogs/operation/addItemsBatch

Add a number of items at once.

For better performance, we recommend using the /v1/async/bags/{catalogId}/items endpoint.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_ITEM_BATCH_CATALOG_CREATE

User role permission required: assets_catalogs: create

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body (required)

application/json · array<catalogs-addItem>

An array of JSON objects with any number of key/value pairs

Responses

Status	Description
`200` `application/json`	Upload status
`400` `text/plain`	Invalid or insufficient data
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items/batch \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}]'

`PATCH` `/catalogs/bags/{catalogId}/enrichment/fields` — Update enrichment fields

/api-reference/data-management#tag/Catalogs/operation/updateEnrichmentFields

Change enrichment fields for given mapping

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_MAPPING_CATALOG_CREATE

User role permission required: assets_catalogs: create

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body

application/json · catalogs-enrichmentUpdateRequest

Field	Type	Required
`action`	string	optional
`paramKey`	string	optional
`enrichmentFields`	array<string>	optional

Responses

Status	Description
`200` `application/json`	Upload status
`400` `text/plain`	Invalid or insufficient data
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/enrichment/fields \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"string","paramKey":"string","enrichmentFields":["string"]}'

`GET` `/catalogs/bags/{catalogId}/items/itemKey/{itemKey}` — Get single item by itemKey

/api-reference/data-management#tag/Catalogs/operation/getItemByKey

Retrieve a single item from a catalog by using the item key (unique identifier of an item in the catalog, for example a product's SKU) of the entry in the Synerise database.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog
`itemKey`	path	string	required	`itemKey` parameter of the item to retrieve

Responses

Status	Description
`200` `application/json`	A single item

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items/itemKey/%7BitemKey%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`DELETE` `/catalogs/bags/{catalogId}/items/itemKey/{itemKey}` — Delete single item by itemKey

/api-reference/data-management#tag/Catalogs/operation/deleteItemByItemKey

Delete a single item by itemKey (unique identifier of an item in the catalog, for example a product's SKU).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_DELETE

User role permission required: assets_catalogs: delete

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog
`itemKey`	path	string	required	`itemKey` parameter of the item to delete

Responses

Status	Description
`200` `application/json`	Success
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items/itemKey/%7BitemKey%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`GET` `/catalogs/bags/{catalogId}/items/{itemId}` — Get single item by database ID

/api-reference/data-management#tag/Catalogs/operation/getItem

Retrieve a single item from a catalog by using the ID of the entry in the Synerise database. If you want to retrieve an item by its unique identifier in the catalog, use /bags/{catalogId}/items/itemKey/{itemKey}.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog
`itemId`	path	integer	required	ID of the item. This is the ID of the entry in the Synerise database, not the unique identifier that you're using in your catalog. The itemId is available in the `id` field of the catalog item when you retrieve items from a catalog: `{ "creationDate": "2020-09-30T11:31:16.314Z", "id": 73753, // this is the itemId "itemKey": "uniqueValue", "lastModified": null, "value": "{\"exampleKey\":\"uniqueValue\",\"exampleKey2\":\"exampleValue\"}", "bag": { "author": "authorName", "creationDate": "2020-09-30T10:52:31.264Z", "id": 1053, // this is the ID of the catalog "lastModified": "2020-09-30T11:41:11.808Z", "name": "sampleCatalog" } },`

Responses

Status	Description
`200` `application/json`	A single item
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items/%7BitemId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/catalogs/bags/{catalogId}/items/{itemId}` — Update single item by database ID

/api-reference/data-management#tag/Catalogs/operation/updateItem

Update a single item from a catalog by using the ID of the entry in the Synerise database.

Update requests are processed according to the time they reach the service.
This means that updates from the synchronous /bags/{catalogId}/items/{itemId} endpoint may overwrite asynchronous operations (see /v1/async/* endpoints) which were sent earlier and queued due to high traffic.
This behavior also applies to requests from Automation and AI feed synchronization, which use the asynchronous mechanism.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_UPDATE

User role permission required: assets_catalogs: update

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog
`itemId`	path	integer	required	ID of the item. This is the ID of the entry in the Synerise database, not the unique identifier that you're using in your catalog. The itemId is available in the `id` field of the catalog item when you retrieve items from a catalog: `{ "creationDate": "2020-09-30T11:31:16.314Z", "id": 73753, // this is the itemId "itemKey": "uniqueValue", "lastModified": null, "value": "{\"exampleKey\":\"uniqueValue\",\"exampleKey2\":\"exampleValue\"}", "bag": { "author": "authorName", "creationDate": "2020-09-30T10:52:31.264Z", "id": 1053, // this is the ID of the catalog "lastModified": "2020-09-30T11:41:11.808Z", "name": "sampleCatalog" } },`

Request body

application/json · object

JSON object with any number of key/value pairs

Responses

Status	Description
`200` `application/json`	A single item
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items/%7BitemId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"property1":null,"property2":null}'

`DELETE` `/catalogs/bags/{catalogId}/items/{itemId}` — Delete single item by database ID

/api-reference/data-management#tag/Catalogs/operation/deleteItem

Delete a single item by ID.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_DELETE

User role permission required: assets_catalogs: delete

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog
`itemId`	path	integer	required	ID of the item. This is the ID of the entry in the Synerise database, not the unique identifier that you're using in your catalog. The itemId is available in the `id` field of the catalog item when you retrieve items from a catalog: `{ "creationDate": "2020-09-30T11:31:16.314Z", "id": 73753, // this is the itemId "itemKey": "uniqueValue", "lastModified": null, "value": "{\"exampleKey\":\"uniqueValue\",\"exampleKey2\":\"exampleValue\"}", "bag": { "author": "authorName", "creationDate": "2020-09-30T10:52:31.264Z", "id": 1053, // this is the ID of the catalog "lastModified": "2020-09-30T11:41:11.808Z", "name": "sampleCatalog" } },`

Responses

Status	Description
`200` `application/json`	Success
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/items/%7BitemId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`GET` `/catalogs/items` — Get all items

/api-reference/data-management#tag/Catalogs/operation/getItemsByBusinessProfileid

Retrieve all items from all catalogs in the Workspace.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`offset`	query	integer	optional	The offset for the search. For example, if your `limit` is 10 and you want to retrieve the third page of items, set the offset to 20. Items with indexes 20 to 29 are returned (the first item on the first page has the index 0).
`limit`	query	integer	optional	The maximum number of items to include in the response. `offset` must be defined. Default: 100

Responses

Status	Description
`200` `application/json`	A list of items in the Workspace
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/catalogs/items?offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/catalogs/bags/{catalogId}/mappings` — Add mapping

/api-reference/data-management#tag/Catalogs/operation/addMapping

Add a new mapping. Mappings can be used to enrich events with data from catalogs.

For example, you can map the product's SKU from the "product.buy" event to the column in the catalog that includes the SKU. Whenever someone purchases an item with that SKU, you can extract data from the catalog (for example, the product's brand and category) and show that additional in the event log in the Synerise GUI.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_MAPPING_CATALOG_CREATE

User role permission required: assets_catalogs: create

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body

application/json · catalogs-eventData

Field	Type	Required	Description
`action`	string	optional	The `action` field of the event
`paramKey`	string	optional	The parameter in the event that corresponds to the catalog column with the unique identifiers

Responses

Status	Description
`200` `application/json`	Mapping data
`400` `text/plain`	Invalid or insufficient data
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/mappings \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"action":"transaction.charge","paramKey":"sku"}'

`GET` `/catalogs/mappings` — Get all mappings

/api-reference/data-management#tag/Catalogs/operation/getMappingsByBP

Retrieve all mappings from the Workspace.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_MAPPING_CATALOG_READ

User role permission required: assets_catalogs: read

Responses

Status	Description
`200` `application/json`	List of mappings
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/catalogs/mappings \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`DELETE` `/catalogs/mappings/{bpActionParamKey}` — Delete mapping

/api-reference/data-management#tag/Catalogs/operation/deleteMappingBykey

Delete a single mapping.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_MAPPING_CATALOG_DELETE

User role permission required: assets_catalogs: delete

Parameters

Name	In	Type	Required	Description
`bpActionParamKey`	path	string	required	The unique identifier of the mapping

Responses

Status	Description
`200` `application/json`	Deletion status
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/catalogs/mappings/%7BbpActionParamKey%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`GET` `/catalogs/itemDetail` — Get single item by unique key

/api-reference/data-management#tag/Catalogs/operation/getItemDetailByKey

Retrieve a single item from a catalog by using the value of the unique identifier (key) in the catalog. If you want to retrieve an item by its ID in the Synerise database, use /bags/{catalogId}/items/{itemId}.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ITEMS_COLLECTOR_CATALOG_READ

User role permission required: assets_catalogs: read

Parameters

Name	In	Type	Required	Description
`catalogName`	query	string	required	Name of the catalog
`key`	query	string	required	Value of the unique identifier of the item in the catalog. When you retrieve an item using this endpoint, the identifier is in the `itemKey` field. `{ "creationDate": "2020-09-30T11:31:16.314Z", "id": 73753, "itemKey": "uniqueValue", // this is the value of the key "lastModified": null, "value": "{\"exampleKey\":\"uniqueValue\",\"exampleKey2\":\"exampleValue\"}", "bag": { "author": "authorName", "creationDate": "2020-09-30T10:52:31.264Z", "id": 1053, "lastModified": "2020-09-30T11:41:11.808Z", "name": "sampleCatalog" } },`

Responses

Status	Description
`200` `application/json`	A single item
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/catalogs/itemDetail?catalogName=SOME_STRING_VALUE&key=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`DELETE` `/catalogs/v2/bags/{catalogId}/items` — Delete all items from a catalog

/api-reference/data-management#tag/Catalogs/operation/deleteBagsItemsV2

Delete all the contents of a catalog.

Information about the keys (columns) remains.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_DELETE

User role permission required: assets_catalogs: delete

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Responses

Status	Description
`200` `application/json`	Items deleted. The `metaData` object always shows a `totalCount` of 1, regardless of the number of deleted items.
`4xx` `application/json`	A problem occurred. See the error message for details.

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/catalogs/v2/bags/%7BcatalogId%7D/items \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`DELETE` `/catalogs/v2/bags/{catalogId}/items/batch` — Delete items by itemKeys

/api-reference/data-management#tag/Catalogs/operation/deleteItemsByItemKeys

Delete items by itemKeys (unique identifier of an item in the catalog, for example a product's SKU). In the Synerise Portal, it's called the Primary key.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_DELETE

User role permission required: assets_catalogs: delete

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body

application/json · array<string>

Array of itemKeys

Responses

Status	Description
`204`	No Content
`401` `application/json`	Unauthorized: token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden: insufficient permissions; wrong consumer scope
`404` `text/plain`	Entity not found

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/catalogs/v2/bags/%7BcatalogId%7D/items/batch \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '["string"]'

`PATCH` `/catalogs/v2/bags/{catalogId}/enable/filtering` — Enable filtering

/api-reference/data-management#tag/Catalogs/operation/enableFilteringV2

Enable filtering for a catalog on selected fields

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_UPDATE

User role permission required: assets_catalogs: update

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body

application/json · catalogs-enableFilteringRequest

Field	Type	Required	Description
`fields`	array<string>	optional

Responses

Status	Description
`200` `application/json`	Upload status

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/catalogs/v2/bags/%7BcatalogId%7D/enable/filtering \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"fields":["string"]}'

`PATCH` `/catalogs/v2/bags/{catalogId}/disable/filtering` — Disable filtering

/api-reference/data-management#tag/Catalogs/operation/disableFilteringV2

Disable filtering for a catalog on selected fields

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: CATALOGS_CATALOG_UPDATE

User role permission required: assets_catalogs: update

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body

application/json · catalogs-disableFilteringRequest

Field	Type	Required	Description
`removeFilters`	boolean	optional

Responses

Status	Description
`200` `application/json`	Number of rows changed

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/catalogs/v2/bags/%7BcatalogId%7D/disable/filtering \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"removeFilters":true}'

`POST` `/catalogs/v1/async/bags/{catalogId}/item` — Add or update item asynchronously

/api-reference/data-management#tag/Catalogs/operation/addItemAsync

Add a single item asynchronously to the catalog. If the item already exists, it's entirely overwritten by the item you send.

Asynchronous requests are processed according to the time they reach the service.
This means that requests to synchronous endpoints (for example, /bags/{catalogId}/items/{itemId} may overwrite asynchronous operations which were sent earlier and queued due to high traffic.
This behavior also applies to requests from Automation and AI feed synchronization, which use the asynchronous mechanism.

The request body can't exceed 256KB.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): CATALOGS_ITEM_BATCH_CREATE, CATALOGS_ITEM_BATCH_CATALOG_CREATE

User role permission required: assets_catalogs: create

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body (required)

application/json · catalogs-addItem

JSON object with any number of key/value pairs

Field	Type	Required	Description
`itemKey`	string	required	The value of the unique key of the item. Slashes (`/`) are not allowed in the value. In the Synerise Portal, this value is saved under Primary key.
`value`	object	required	Properties of the item. Can be an empty object.

Responses

Status	Description
`204`	Operation added to queue

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/item \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}'

`PATCH` `/catalogs/v1/async/bags/{catalogId}/item` — Add or update (partial) item asynchronously

/api-reference/data-management#tag/Catalogs/operation/updateItemAsync

Update a single item asynchronously to the catalog. If the item doesn't exist, it will be created.

This endpoint allows you to perform partial updates - you can send only the properties that you want to add/modify, instead of sending the entire item.

The request body can't exceed 256KB.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): CATALOGS_ITEM_BATCH_UPDATE, CATALOGS_ITEM_BATCH_CATALOG_UPDATE

User role permission required: assets_catalogs: update

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body (required)

application/json · catalogs-addItem

JSON object with any number of key/value pairs

Field	Type	Required	Description
`itemKey`	string	required	The value of the unique key of the item. Slashes (`/`) are not allowed in the value. In the Synerise Portal, this value is saved under Primary key.
`value`	object	required	Properties of the item. Can be an empty object.

Responses

Status	Description
`204`	Operation added to queue

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/item \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}'

`POST` `/catalogs/v1/async/bags/{catalogId}/items` — Batch add or update items asynchronously

/api-reference/data-management#tag/Catalogs/operation/addItemsBatchAsync

Add a number of items asynchronously at once. If an item already exists, it's entirely overwritten by the item you send.

The request body can't exceed 256KB.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): CATALOGS_ITEM_BATCH_CREATE, CATALOGS_ITEM_BATCH_CATALOG_CREATE

User role permission required: assets_catalogs: create

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body (required)

application/json · array<catalogs-addItem>

JSON object with any number of key/value pairs

Responses

Status	Description
`204`	Operation added to queue

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/items \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}]'

`PATCH` `/catalogs/v1/async/bags/{catalogId}/items` — Batch add or update (partial) items asynchronously

/api-reference/data-management#tag/Catalogs/operation/updateItemsBatchAsync

Update a number of items asynchronously at once. If an item doesn't exist, it will be created.

This endpoint allows you to perform partial updates - you can send only the properties that you want to add/modify, instead of sending the entire item.

The request body can't exceed 256KB.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): CATALOGS_ITEM_BATCH_UPDATE, CATALOGS_ITEM_BATCH_CATALOG_UPDATE

User role permission required: assets_catalogs: update

Parameters

Name	In	Type	Required	Description
`catalogId`	path	integer	required	ID of the catalog

Request body (required)

application/json · array<catalogs-addItem>

JSON object with any number of key/value pairs

Responses

Status	Description
`204`	Operation added to queue

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/catalogs/v1/async/bags/%7BcatalogId%7D/items \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"itemKey":"sku1357","value":{"itemCategory":"smartphone","itemColor":"blue"}}]'

Asset tags

`GET` `/tags-collector/directories` — Get all directories

/api-reference/data-management#tag/Asset-tags/operation/getTagDirectories

Gets all tag directories from the Workspace.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_READ

User role permission required: assets_tags: read

Responses

Status	Description
`200` `application/json`	OK
`401`	Unauthorized
`403`	Forbidden

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/tags-collector/directories

`POST` `/tags-collector/directories` — Create directory

/api-reference/data-management#tag/Asset-tags/operation/createDirectory

Creates a directory.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_CREATE

User role permission required: assets_tags: create

Request body (required)

application/json · tags-collector-DirectoryCreateRequest-collector

Field	Type	Required	Description
`name`	string	required	Name of the directory
`params`	object	optional	Free-form parameters
`type`	string	optional	HashID of the directory type

Responses

Status	Description
`201` `application/json`	Created
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/tags-collector/directories \
  --header 'content-type: application/json' \
  --data '{"name":"string","params":{"property1":"string","property2":"string"},"type":"string"}'

`GET` `/tags-collector/directories/types` — Get directory types

/api-reference/data-management#tag/Asset-tags/operation/getDirectoryTypes

Gets all directory types.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_READ

User role permission required: assets_tags: read

Responses

Status	Description
`200` `application/json`	OK
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/tags-collector/directories/types

`POST` `/tags-collector/directories/types` — Create directory type

/api-reference/data-management#tag/Asset-tags/operation/createDirectoryType

Creates a directory type.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_UPDATE

User role permission required: assets_tags: update

Request body (required)

application/json · tags-collector-DirectoryTypeCreateRequest-collector

Field	Type	Required	Description
`name`	string	required	Name of the directory type

Responses

Status	Description
`201` `application/json`	Created
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/tags-collector/directories/types \
  --header 'content-type: application/json' \
  --data '{"name":"string"}'

`PATCH` `/tags-collector/directories/{directoryHash}` — Update directory

/api-reference/data-management#tag/Asset-tags/operation/updateDirectory

Updates a directory.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_UPDATE

User role permission required: assets_tags: update

Parameters

Name	In	Type	Required	Description
`directoryHash`	path	string	required	Hash ID of the directory

Request body (required)

application/json · tags-collector-DirectoryUpdateRequest-collector

Field	Type	Required	Description
`name`	string	optional	Name of the directory
`params`	object	optional	Free-form parameters

Responses

Status	Description
`200` `application/json`	OK
`204`	No Content
`401`	Unauthorized
`403`	Forbidden

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/tags-collector/directories/%7BdirectoryHash%7D \
  --header 'content-type: application/json' \
  --data '{"name":"string","params":{"property1":"string","property2":"string"}}'

`DELETE` `/tags-collector/directories/{directoryHash}` — Delete directory

/api-reference/data-management#tag/Asset-tags/operation/deleteDirectory

Deletes a directory.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_DELETE

User role permission required: assets_tags: delete

Parameters

Name	In	Type	Required	Description
`directoryHash`	path	string	required	Hash ID of the directory

Responses

Status	Description
`200`	OK
`204`	No Content
`401`	Unauthorized
`403`	Forbidden

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/tags-collector/directories/%7BdirectoryHash%7D

`GET` `/tags-collector/directories/{directoryHash}/tags` — Get tags from directory

/api-reference/data-management#tag/Asset-tags/operation/getTagsUsingGET

Retrieve tags from a directory.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_READ

User role permission required: assets_tags: read

Parameters

Name	In	Type	Required	Description
`directoryHash`	path	string	required	Hash ID of the directory

Responses

Status	Description
`200` `application/json`	OK
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/tags-collector/directories/%7BdirectoryHash%7D/tags

`POST` `/tags-collector/directories/{directoryHash}/tags` — Assign tags to directory

/api-reference/data-management#tag/Asset-tags/operation/assignTagsUsingPOST

Assign tags to a directory.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_UPDATE

User role permission required: assets_tags: update

Parameters

Name	In	Type	Required	Description
`directoryHash`	path	string	required	Hash ID of the directory

Request body (required)

application/json · array<string>

Responses

Status	Description
`200`	OK
`201`	Created
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/tags-collector/directories/%7BdirectoryHash%7D/tags \
  --header 'content-type: application/json' \
  --data '["string"]'

`DELETE` `/tags-collector/directories/{directoryHash}/tags` — Unassign tags from directory

/api-reference/data-management#tag/Asset-tags/operation/unassignTagUsingDELETE

Unassign tags from a directory. This does not delete the tags or the directory.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_DELETE

User role permission required: assets_tags: delete

Parameters

Name	In	Type	Required	Description
`directoryHash`	path	string	required	Hash ID of the directory

Request body (required)

application/json · array<string>

Responses

Status	Description
`200`	OK
`204`	No Content
`401`	Unauthorized
`403`	Forbidden

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/tags-collector/directories/%7BdirectoryHash%7D/tags \
  --header 'content-type: application/json' \
  --data '["string"]'

`PUT` `/tags-collector/directories/{directoryHash}/types` — Update directory type

/api-reference/data-management#tag/Asset-tags/operation/updateTypeUsingPUT

Update the type of a directory.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_DIRECTORY_UPDATE

User role permission required: assets_tags: update

Parameters

Name	In	Type	Required	Description
`directoryHash`	path	string	required	Hash ID of the directory

Request body (required)

application/json · tags-collector-DirectoryTypeUpdateRequest-collector

Field	Type	Required	Description
`directoryTypeHash`	string	optional	HashID of the directory type

Responses

Status	Description
`200` `application/json`	OK
`201`	Created
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/tags-collector/directories/%7BdirectoryHash%7D/types \
  --header 'content-type: application/json' \
  --data '{"directoryTypeHash":"string"}'

`GET` `/tags-collector/tags` — Get tag list

/api-reference/data-management#tag/Asset-tags/operation/getTagList

Gets a paginated list of tags that can be assigned to assets, for example promotions.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_TAG_READ

User role permission required: assets_tags: read

Parameters

Name	In	Type	Required	Description
`page`	query	integer	optional	Page to retrieve
`size`	query	integer	optional	Limit of items per page
`directoryType`	query	string	optional	Directory type

Responses

Status	Description
`200` `application/json`	OK
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/tags-collector/tags?page=SOME_INTEGER_VALUE&size=SOME_INTEGER_VALUE&directoryType=SOME_STRING_VALUE'

`POST` `/tags-collector/tags` — Create tag

/api-reference/data-management#tag/Asset-tags/operation/createTag

Creates a tag that can be assigned to assets, for example promotions.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_TAG_CREATE

User role permission required: assets_tags: create

Request body (required)

application/json · tags-collector-TagCreateRequest-collector

Field	Type	Required	Description
`color`	string	optional	Hex code of the tag color
`description`	string	optional	Description of the tag
`directory`	string	optional	Hash ID of the directory where the tag is assigned
`icon`	string	optional	URL of the tag's icon
`priority`	integer	required	Tag priority. Lower values mean higher priority.
`value`	string	required	Name of the tag

Responses

Status	Description
`201` `application/json`	Created
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/tags-collector/tags \
  --header 'content-type: application/json' \
  --data '{"color":"string","description":"string","directory":"string","icon":"string","priority":0,"value":"string"}'

`PATCH` `/tags-collector/tags/{tagHash}` — Update tag

/api-reference/data-management#tag/Asset-tags/operation/updateTag

Updates a tag definition.

API consumers: Synerise User, Profile (Client), Workspace (Business Profile)

API key permission required: TAGS_COLLECTOR_TAG_UPDATE

User role permission required: assets_tags: update

Parameters

Name	In	Type	Required	Description
`tagHash`	path	string	required	HashID of a tag

Request body (required)

application/json · tags-collector-TagUpdateRequest-collector

Field	Type	Required	Description
`color`	string	optional	Hex code of the tag color
`description`	string	optional	Description of the tag
`directory`	string	optional	Hash ID of the directory where the tag is assigned
`icon`	string	optional	URL of the tag's icon
`priority`	integer	optional	Tag priority. Lower values mean higher priority.
`value`	string	optional	Name of the tag

Responses

Status	Description
`200` `application/json`	OK
`401`	Unauthorized
`403`	Forbidden

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/tags-collector/tags/%7BtagHash%7D \
  --header 'content-type: application/json' \
  --data '{"color":"string","description":"string","directory":"string","icon":"string","priority":0,"value":"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

Name	In	Type	Required	Description
`Api-Version`	header	enum<"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

Field	Type	Required	Description
`email`	string	optional	The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+))\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication. 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.
`phone`	string	optional	Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`customId`	string	optional	A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`firstName`	string	optional	Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`lastName`	string	optional	Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`displayName`	string	optional	Currently unused
`uuid`	string	optional	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`avatarUrl`	string	optional	URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`birthDate`	string	optional	Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. Must be a date in the past. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
`company`	string	optional	Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`city`	string	optional	Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`address`	string	optional	Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`zipCode`	string	optional	Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`province`	string	optional	Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`countryCode`	string	optional	Code of profile's country of residence in accordance with the ISO 3166 format
`sex`	enum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">	optional	Profile's sex
`agreements`	object	optional	This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
`attributes`	object	optional	This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes 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`
`tags`	array<string>	optional	Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Status	Description
`202`	Accepted, queued for processing
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`sourceCustomIDs`	path	string	required	Comma-delimited string with custom IDs of the profiles to merge
`targetCustomID`	path	string	required	The custom ID of the profile to merge the `sourceCustomIDs` into
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`200` `application/json`	Request completed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Source 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 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

Name	In	Type	Required	Description
`fromClientIds`	path	string	required	Comma-delimited string with client IDs of the profiles to merge
`toClientId`	path	integer	required	The ID of the profile to merge the `fromClientIds` into
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`200` `application/json`	Request completed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Source 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

Name	In	Type	Required	Description
`Accept`	header	enum<"application/json">	required
`Api-Version`	header	enum<"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

Status	Description
`202`	Request 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/json`	Invalid data in some entries. Correct entries are sent for further processing, the invalid ones are rejected.
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	The 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-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`200` `application/json`	Details of a single profile
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	The 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-Version`	header	enum<"4.4">	required

Request body (required)

application/json · api-service-CreateClientRequestBody-apiv4

Field	Type	Required	Description
`email`	string	optional	The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+))\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication. 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.
`phone`	string	optional	Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`customId`	string	optional	A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`firstName`	string	optional	Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`lastName`	string	optional	Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`displayName`	string	optional	Currently unused
`uuid`	string	optional	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`avatarUrl`	string	optional	URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`birthDate`	string	optional	Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. Must be a date in the past. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
`company`	string	optional	Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`city`	string	optional	Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`address`	string	optional	Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`zipCode`	string	optional	Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`province`	string	optional	Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`countryCode`	string	optional	Code of profile's country of residence in accordance with the ISO 3166 format
`sex`	enum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">	optional	Profile's sex
`agreements`	object	optional	This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
`attributes`	object	optional	This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes 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`
`tags`	array<string>	optional	Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Status	Description
`202`	Accepted, queued for processing
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile not found
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	The 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.
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`202`	Accepted
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile 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

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

Name	In	Type	Required	Description
`clientEmail`	path	string	required	The profile's email address Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+))\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the patternn (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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-Version`	header	enum<"4.4">	required

Request body (required)

application/json · api-service-CreateClientRequestBody-apiv4

Field	Type	Required	Description
`email`	string	optional	The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+))\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication. 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.
`phone`	string	optional	Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`customId`	string	optional	A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`firstName`	string	optional	Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`lastName`	string	optional	Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`displayName`	string	optional	Currently unused
`uuid`	string	optional	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`avatarUrl`	string	optional	URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`birthDate`	string	optional	Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. Must be a date in the past. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
`company`	string	optional	Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`city`	string	optional	Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`address`	string	optional	Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`zipCode`	string	optional	Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`province`	string	optional	Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`countryCode`	string	optional	Code of profile's country of residence in accordance with the ISO 3166 format
`sex`	enum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">	optional	Profile's sex
`agreements`	object	optional	This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
`attributes`	object	optional	This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes 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`
`tags`	array<string>	optional	Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Status	Description
`202`	Accepted, queued for processing
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile not found
`415` `application/json`	Unsupported 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

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

Name	In	Type	Required	Description
`customId`	path	string	required	The 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-Version`	header	enum<"4.4">	required

Request body (required)

application/json · api-service-CreateClientRequestBody-apiv4

Field	Type	Required	Description
`email`	string	optional	The profile's e-mail address. Must match the pattern (ECMA flavor): `/^(([^<>()[\]\\.,;:\s@\\"]+(\.[^<>()[\]\\.,;:\s@\\"]+))\|(\\".+\\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])\|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` By default, email is a unique identifier. If non-unique emails are enabled, this field should not be used. It is no longer an identifier. The configuration of non-unique emails includes creating an email parameter for communication. 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.
`phone`	string	optional	Phone number of the profile Must match the pattern (ECMA flavor): `/(^\+[0-9 \-()/]{6,19}$)\|(^[0-9 \-()/]{6,20}$)/` The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`customId`	string	optional	A custom ID for the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`firstName`	string	optional	Profile's first name. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`lastName`	string	optional	Profile's last name The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`displayName`	string	optional	Currently unused
`uuid`	string	optional	UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/` 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.
`avatarUrl`	string	optional	URL of the profile's avatar picture The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`birthDate`	string	optional	Date of birth in the profile. Must be in `yyyy-mm-dd` format and later than `1900-01-01`. Must be a date in the past. IMPORTANT: Months and days must be zero-padded. For example: May 3, 1993 is `1993-05-03`.
`company`	string	optional	Profiles's company The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`city`	string	optional	Profile's city of residence. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`address`	string	optional	Profile's street address. The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`zipCode`	string	optional	Profile's zip code The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`province`	string	optional	Profile's province of residence The value: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)
`countryCode`	string	optional	Code of profile's country of residence in accordance with the ISO 3166 format
`sex`	enum<"FEMALE", "MALE", "NOT_SPECIFIED", "OTHER">	optional	Profile's sex
`agreements`	object	optional	This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
`attributes`	object	optional	This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes 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`
`tags`	array<string>	optional	Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Status	Description
`202`	Accepted, queued for processing
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile not found
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`customId`	path	string	required	The 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-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`202`	Accepted
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile 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

Name	In	Type	Required	Description
`identifierType`	path	enum<"by-custom-id", "by-phone", "by-uuid", "by-email">	required	The type of profile identifier to use for the request
`identifierValue`	path	string	required	The value of the selected identifier. The value must be URL-encoded.
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`200` `application/json`	Details of a single profile
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile not found or access blocked by PII protection settings
`415` `application/json`	Unsupported 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

Name	In	Type	Required	Description
`phoneNumber`	path	string	required	The 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-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4">	required

Responses

Status	Description
`200` `application/json`	Returns an array of profile details.
`400` `application/json`	Bad Request
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Profile not found or access blocked by PII protection settings
`415` `application/json`	Unsupported 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:

GET /v4/clients/{clientId}
GET /v4/clients/{identifierType}/{identifierValue}

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

Name	In	Type	Required	Description
`clientId`	path	integer	required	Profile 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

Status	Description
`200` `application/json`	Profile details
`404` `text/plain`	Resource 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:

POST /v4/clients/{clientId}
POST /v4/clients/by-email/{clientEmail}
POST /v4/clients/by-customid/{customId}

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

Name	In	Type	Required	Description
`clientId`	path	integer	required	Profile 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

Field	Type	Required	Description
`uuid`	string	optional	UUID 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.
`email`	string	optional	Profile'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.
`firstname`	string	optional	Profile's first name
`lastName`	string	optional	Profile's last name
`custom_identify`	string	optional	A 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.
`company`	string	optional	Profile's company
`phone`	string	optional	Profile'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.
`address`	string	optional	Profile's street address
`birthdate`	string	optional	Profile's date of birth. Must be a past date.
`city`	string	optional	Profile's city of residence
`zipCode`	string	optional	Profile's zip code
`province`	string	optional	Profile's province of residence
`country_id`	string	optional	ID of the Profile's country of residence
`countryCode`	string	optional	Code of Profile's country of residence
`avatarUrl`	string	optional	URL of the Profile's avatar picture
`sex`	enum<"0", "1", "2", "3">	optional	Profile's sex. 0: undefined 1: female 2: male 3: other
`tags`	array<string>	optional	Custom tags. They can be used, for example, to group Profiles.
`additionalProperties`		optional	Additional 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

Status	Description
`200` `application/json`	Profile 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

Field	Type	Required	Description
`name`	string	required	Name of the export, visible at https://app.synerise.com/assets/
`fields`	array<string>	required	Profile attributes to export. The first attribute in this array MUST BE `id`
`agreementFilter`	enum<"NONE", "EMAIL", "WEB_PUSH", "PUSH", …>	required	You can filter the profiles by their marketing agreement. `NONE` means no filter.
`segmentationHash`	string	required	UUID 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.
`tags`	array<string>	optional	Profile 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".
`expressions`	array<string>	optional	UUIDs 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.
`aggregates`	array<string>	optional	UUIDs 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.
`segmentations`	array<string>	optional	UUIDs 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".
`excludedIds`	array<number>	required	List of clientIds to exclude from the exported data

Responses

Status	Description
`200` `application/json`	Export task created and queued
`400` `application/json`	Invalid 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

Name	In	Type	Required	Description
`taskId`	path	string	required	Unique ID of the export task

Responses

Status	Description
`200` `application/json`	Status 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

Name	In	Type	Required	Description
`taskId`	path	string	required	Unique ID of the export task
`offset`	query	number	required	The index of the first record to retrieve. Use this to paginate the exported data.
`limit`	query	integer	required	The number of records to retrieve. Use this to paginate the exported data.

Responses

Status	Description
`200` `application/json`	Exported profile data
`400` `application/json`	Invalid 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	Profile ID

Responses

Status	Description
`200` `application/json`	An array of notes
`401`	Unauthorized
`403`	Forbidden
`404`	Not 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	Profile ID

Request body

application/json · notes-service-NoteRequest

Field	Type	Required	Description
`subject`	string	optional	The title of the note
`body`	string	optional	Text of the note

Responses

Status	Description
`200` `application/json`	OK
`201`	Created
`401`	Unauthorized
`403`	Forbidden
`404`	Not 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	Profile ID
`noteId`	path	string	required	Note UUID

Responses

Status	Description
`200` `application/json`	OK
`401`	Unauthorized
`403`	Forbidden
`404`	Not 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	Profile ID
`noteId`	path	string	required	Note UUID

Request body

application/json · notes-service-NoteRequest

Field	Type	Required	Description
`subject`	string	optional	The title of the note
`body`	string	optional	Text of the note

Responses

Status	Description
`200` `application/json`	OK
`201`	Created
`401`	Unauthorized
`403`	Forbidden
`404`	Not 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

Name	In	Type	Required	Description
`clientId`	path	integer	required	Profile ID
`noteId`	path	string	required	Note UUID

Responses

Status	Description
`200`	OK
`204`	No Content
`401`	Unauthorized
`403`	Forbidden

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

Name	In	Type	Required	Description
`clientID`	path	string	required	The ID of the Profile

Request body

application/json · sauth-ClientLogoutRequest

Field	Type	Required	Description
`action`	enum<"LOGOUT", "LOGOUT_WITH_SESSION_CLEARING">	optional

Responses

Status	Description
`200`	OK
`401` `application/json`	JWT missing, expired, or invalid
`403` `application/json`	Insufficient permissions or wrong JWT scope (for example, profile token where a workspace token was required)
`404`	Profile 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"}'

Analytics: Expressions

`POST` `/analytics/{namespace}/expressions/visible-for-client/by/{identifierType}` — Get expressions for profile card

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-client-card-expressions-get

Retrieve expressions to display on a profile's card in the Profiles module ("isVisibleForClientProfile": true in the expression config).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_EXPRESSION_FOR_CLIENT_READ

User role permission required (at least one): analytics: read, client_analytics_preview: read

Parameters

Name	In	Type	Required	Description
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.

Request body

application/json · object

Field	Type	Required	Description
`identifierValue`	string	required	Value of the selected identifier. Note that IDs must also be sent as strings.

Responses

Status	Description
`200` `application/json`	List of calculated expressions configured as visible on the profile card
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/expressions/visible-for-client/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string"}'

`POST` `/analytics/{namespace}/expressions/{expressionId}/calculate/by/{identifierType}` — Calculate expression for profile

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-expression-calculate

Calculate the result of an expression in context of a single profile.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_EXPRESSION_FOR_CLIENT_READ

User role permission required: analytics: read

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`expressionId`	path	string	required	Expression ID
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type

Request body

application/json · object

Field	Type	Required	Description
`identifierValue`	string	required	Value of the selected identifier. Note that IDs must also be sent as strings.

Responses

Status	Description
`200` `application/json`	Expression result
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/expressions/%7BexpressionId%7D/calculate/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string"}'

`GET` `/analytics/{namespace}/expressions` — List expressions

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-expressions-list

Returns a paginated list of expressions.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_EXPRESSIONS_LIST_READ

User role permission required: analytics: read

Parameters

Name	In	Type	Required	Description
`page`	query	integer	optional	The number of the page to retrieve
`limit`	query	integer	optional	Limit of items per page
`search`	query	string	optional	A string to search for in analyses' titles
`sortBy`	query	enum<"name:asc", "name:desc", "author:asc", "author:desc", …>	optional	You can sort the results. The sorting direction is selected by adding `asc` or `desc`, for example `sortBy=name:desc`.
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`directoryId`	query	string	optional	Unique ID of the directory to retrieve analyses from
`ids`	query	string	optional	Comma-separated list of IDs (in UUID format) to filter results through

Responses

Status	Description
`200` `application/json`	List of expressions
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/analytics/%7Bnamespace%7D/expressions?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&search=SOME_STRING_VALUE&sortBy=name%3Aasc&directoryId=SOME_STRING_VALUE&ids=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/analytics/{namespace}/expressions` — Create expression

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-expressions-create

Create an expression that is saved in the database and can be used in other analyses.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_EXPRESSIONS_CREATE, ANALYTICS_BACKEND_EXPRESSION_CREATE

User role permission required: analytics: create

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.

Request body

application/json · analytics-expressionCreateRequestBody

Field	Type	Required	Description
`isVisibleForClientProfile`	boolean	required	When set to `true`, information about this analysis is shown on a profile's card.
`analysis`		required	Details of an expression analysis

Responses

Status	Description
`201` `application/json`	Create expression
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/expressions \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"isVisibleForClientProfile":true,"analysis":{"type":"EVENT","action":{"id":0,"name":"page.visit"},"name":"string","description":"string","expression":{"type":"VALUE","title":"string","value":{"type":"EVENT","attribute":{"type":"PARAM","param":"string","id":0}}}}}'

`GET` `/analytics/{namespace}/expressions/{expressionId}` — Get expression details

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-expressions-get

Retrieve information about an expression analysis

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_EXPRESSIONS_READ, ANALYTICS_BACKEND_EXPRESSION_READ

User role permission required: analytics: read

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`expressionId`	path	string	required	Expression ID

Responses

Status	Description
`200` `application/json`	Get expression details
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/expressions/%7BexpressionId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`PUT` `/analytics/{namespace}/expressions/{expressionId}` — Update expression

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-expressions-update

Update an existing expression

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_EXPRESSIONS_UPDATE, ANALYTICS_BACKEND_EXPRESSION_UPDATE

User role permission required: analytics: update

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`expressionId`	path	string	required	Expression ID

Request body

application/json · analytics-expressionCreateRequestBody

Field	Type	Required	Description
`isVisibleForClientProfile`	boolean	required	When set to `true`, information about this analysis is shown on a profile's card.
`analysis`		required	Details of an expression analysis

Responses

Status	Description
`200`	Update expression
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/expressions/%7BexpressionId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"isVisibleForClientProfile":true,"analysis":{"type":"EVENT","action":{"id":0,"name":"page.visit"},"name":"string","description":"string","expression":{"type":"VALUE","title":"string","value":{"type":"EVENT","attribute":{"type":"PARAM","param":"string","id":0}}}}}'

`DELETE` `/analytics/{namespace}/expressions/{expressionId}` — Delete expression

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-expressions-delete

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_EXPRESSIONS_DELETE, ANALYTICS_BACKEND_EXPRESSION_DELETE

User role permission required: analytics: delete

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`expressionId`	path	string	required	Expression ID

Responses

Status	Description
`204`	Delete expression
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/expressions/%7BexpressionId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/analytics/{namespace}/expressions/preview/by/{identifierType}` — Get expression preview

/api-reference/data-management#tag/Analytics:-Expressions/operation/analytics2-expression-preview-v2

Retrieve expression preview value. Previews are only available for CLIENT-type expressions. This request doesn't save the expression.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_EXPRESSION_FOR_CLIENT_READ

User role permission required (at least one): analytics: read, client_analytics_preview: read

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type

Request body

application/json · analytics-ExpressionPreviewRequestWithClient

Field	Type	Required	Description
`identifierValue`	string	required	Value of the selected identifier. Note that IDs must also be sent as strings.
`expression`	object	required	Details of a profile expression. In the Synerise Portal, they are called attribute expressions.

Responses

Status	Description
`200` `application/json`	Expression preview result
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/expressions/preview/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string","expression":{"type":"CLIENT","name":"string","description":"string","expression":{"type":"VALUE","title":"string","value":{"type":"CLIENT","attribute":{"type":"SEGMENTATION","id":"497f6eca-6276-4993-bfeb-53cbbbba6f08"}}}}}'

Analytics: Aggregates

`POST` `/analytics/analytics/definitions-manager/aggregates/{aggregateId}/client/{clientId}/calculate/histogram` — Calculate aggregate for profile with period conditions

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics-calculate-aggregate-for-profile-with-period-uuid

Calculate the results of an aggregate in context of a single profile. The results can be date-filtered and aggregated in time periods.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_AGGREGATE_HISTOGRAM_FOR_CLIENT_READ

User role permission required: analytics: read

Parameters

Name	In	Type	Required	Description
`aggregateId`	path	string	required	Aggregate ID
`clientId`	path	integer	required	Client ID

Request body

application/json · analytics-AggregateHistogramRequest

Field	Type	Required	Description
`variables`	array<analytics-Variable>	required	A list of variable values to use in this calculation
`dateFilter`		required	Definition of a date filter. Only data that meets the result of the filter will be included in the analysis. For no filter, leave this object empty. An absolute date filter lets you define static dates and times that always apply to the analysis. A relative date filter lets you create a date filter that goes back a certain time from the moment of calculating the analysis.
`aggregateDataBy`	object	required	The interval for grouping data

Responses

Status	Description
`200` `application/json`	Aggregate calculation result
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/analytics/definitions-manager/aggregates/%7BaggregateId%7D/client/%7BclientId%7D/calculate/histogram \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"variables":[{"name":"string","value":"string"}],"dateFilter":{"type":"ABSOLUTE","from":"2019-08-24T14:15:22Z","to":"2019-08-24T14:15:22Z","filter":{"type":"DAILY","nestingType":"IN_PLACE","from":"string","to":"string","inverted":false}},"aggregateDataBy":{"type":"YEARS","value":0}}'

`POST` `/analytics/{namespace}/aggregates/preview/by/{identifierType}` — Get aggregate preview

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-aggregate-preview-v2

Retrieve aggregate preview value. Previews are only available for the AGGREGATE type (profile aggregate). This request doesn't save an aggregate to the database.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_AGGREGATES_READ, ANALYTICS_BACKEND_AGGREGATE_READ

User role permission required: analytics_aggregates: read

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type

Request body

application/json · analytics-PreviewAggregateRequest

Field	Type	Required	Description
`aggregate`		required
`identifierValue`	string	required	Value of the selected identifier. Note that IDs must also be sent as strings.

Responses

Status	Description
`200` `application/json`	Aggregate preview
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates/preview/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"aggregate":{"oldId":0,"aggregateType":"AGGREGATE","name":"string","description":"string","action":{"id":0,"name":"page.visit"},"attribute":{"type":"PARAM","param":"string","id":0},"type":"AVG","level":0.01,"dateFilter":{"type":"ABSOLUTE","from":"2019-08-24T14:15:22Z","to":"2019-08-24T14:15:22Z","filter":{"type":"DAILY","nestingType":"IN_PLACE","from":"string","to":"string","inverted":false}},"size":0,"unique":false,"expressions":[{"attribute":{"type":"PARAM","param":"string","id":0},"constraint":{"type":"BOOL","logic":"IS_TRUE"}}]},"identifierValue":"string"}'

`POST` `/analytics/{namespace}/aggregates/visible-for-client/by/{identifierType}` — Get aggregates for profile card

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-client-card-aggregates-get

Retrieve aggregates to display on a profile's card in the Profiles module ("isVisibleForClientProfile": true) in the expression config).

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_AGGREGATE_FOR_CLIENT_READ

User role permission required (at least one): analytics: read, client_analytics_preview: read

Parameters

Name	In	Type	Required	Description
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.

Request body

application/json · object

Field	Type	Required	Description
`identifierValue`	string	required	Value of the selected identifier. Note that IDs must also be sent as strings.

Responses

Status	Description
`200` `application/json`	List of calculated aggregates configured as visible on the profile card
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates/visible-for-client/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string"}'

`POST` `/analytics/{namespace}/aggregates/{aggregateId}/calculate/by/{identifierType}` — Calculate aggregate for profile

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-aggregate-calculate

Calculate the result of an existing aggregate in context of a single profile.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_AGGREGATE_FOR_CLIENT_READ

User role permission required: analytics: read

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`aggregateId`	path	string	required	Aggregate ID
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Profile identifier type

Request body

application/json · object

Field	Type	Required	Description
`identifierValue`	string	required	Value of the selected identifier. Note that IDs must also be sent as strings.

Responses

Status	Description
`200` `application/json`	Aggregate result
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates/%7BaggregateId%7D/calculate/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string"}'

`GET` `/analytics/{namespace}/aggregates` — List aggregates

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-aggregates-list

Returns a paginated list of aggregates.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: ANALYTICS_BACKEND_AGGREGATES_LIST_READ

User role permission required: analytics: read

Parameters

Name	In	Type	Required	Description
`page`	query	integer	optional	The number of the page to retrieve
`limit`	query	integer	optional	Limit of items per page
`search`	query	string	optional	A string to search for in analyses' titles
`sortBy`	query	enum<"name:asc", "name:desc", "author:asc", "author:desc", …>	optional	You can sort the results. The sorting direction is selected by adding `asc` or `desc`, for example `sortBy=name:desc`.
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`directoryId`	query	string	optional	Unique ID of the directory to retrieve analyses from
`ids`	query	string	optional	Comma-separated list of IDs (in UUID format) to filter results through
`aggregateType`	query	enum<"AGGREGATE", "RUNNING_AGGREGATE">	optional	Filter by aggregate type

Responses

Status	Description
`200` `application/json`	List of aggregates
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&search=SOME_STRING_VALUE&sortBy=name%3Aasc&directoryId=SOME_STRING_VALUE&ids=SOME_STRING_VALUE&aggregateType=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`POST` `/analytics/{namespace}/aggregates` — Create aggregate

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-aggregate-create

Create an aggregate analysis and save it to the database.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_AGGREGATES_CREATE, ANALYTICS_BACKEND_AGGREGATE_CREATE

User role permission required: analytics_aggregates: create

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.

Request body

application/json · analytics-AggregateRequest

Field	Type	Required	Description
`analysis`		required	Definition of the aggregate
`isVisibleForClientProfile`	boolean	required	When set to `true`, information about this analysis is shown on a profile's card.
`previewDefaultObjectId`	number	optional	The ID of the default profile for generating a preview of the results.

Responses

Status	Description
`201` `application/json`	Aggregate has been created
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"analysis":{"aggregateType":"RUNNING_AGGREGATE","excludeCurrent":true,"timeWindow":{"type":"YEARS","value":0},"name":"string","description":"string","action":{"id":0,"name":"page.visit"},"attribute":{"type":"PARAM","param":"string","id":0},"type":"AVG","level":0.01,"dateFilter":{"type":"ABSOLUTE","from":"2019-08-24T14:15:22Z","to":"2019-08-24T14:15:22Z","filter":{"type":"DAILY","nestingType":"IN_PLACE","from":"string","to":"string","inverted":false}},"size":0,"unique":false,"expressions":[{"attribute":{"type":"PARAM","param":"string","id":0},"constraint":{"type":"BOOL","logic":"IS_TRUE"}}]},"isVisibleForClientProfile":true,"previewDefaultObjectId":0}'

`GET` `/analytics/{namespace}/aggregates/{aggregateId}` — Get aggregate details

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-aggregate-get

Retrieve all data about an aggregate definition.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_AGGREGATES_READ, ANALYTICS_BACKEND_AGGREGATE_READ

User role permission required: analytics_aggregates: read

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`aggregateId`	path	string	required	Aggregate ID

Responses

Status	Description
`200` `application/json`	Details of the aggregate
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates/%7BaggregateId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

`PUT` `/analytics/{namespace}/aggregates/{aggregateId}` — Update aggregate

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-aggregate-update

Update an aggregate.

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_AGGREGATES_UPDATE, ANALYTICS_BACKEND_AGGREGATE_UPDATE

User role permission required: analytics_aggregates: update

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`aggregateId`	path	string	required	Aggregate ID

Request body

application/json · analytics-AggregateUpdateRequest

Field	Type	Required	Description
`analysis`		required
`isVisibleForClientProfile`	boolean	required	When set to `true`, information about this analysis is shown on a profile's card.
`previewDefaultObjectId`	number	optional	The ID of the default profile for generating a preview of the results.

Responses

Status	Description
`200`	Aggregate updated
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates/%7BaggregateId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"analysis":{"oldId":0,"aggregateType":"RUNNING_AGGREGATE","excludeCurrent":true,"timeWindow":{"type":"YEARS","value":0},"name":"string","description":"string","action":{"id":0,"name":"page.visit"},"attribute":{"type":"PARAM","param":"string","id":0},"type":"AVG","level":0.01,"dateFilter":{"type":"ABSOLUTE","from":"2019-08-24T14:15:22Z","to":"2019-08-24T14:15:22Z","filter":{"type":"DAILY","nestingType":"IN_PLACE","from":"string","to":"string","inverted":false}},"size":0,"unique":false,"expressions":[{"attribute":{"type":"PARAM","param":"string","id":0},"constraint":{"type":"BOOL","logic":"IS_TRUE"}}]},"isVisibleForClientProfile":true,"previewDefaultObjectId":0}'

`DELETE` `/analytics/{namespace}/aggregates/{aggregateId}` — Delete aggregate

/api-reference/data-management#tag/Analytics:-Aggregates/operation/analytics2-aggregate-delete

API consumers: Synerise User, Workspace (Business Profile)

API key permissions required (at least one): ANALYTICS_BACKEND_AGGREGATES_DELETE, ANALYTICS_BACKEND_AGGREGATE_DELETE

User role permission required: analytics_aggregates: delete

Parameters

Name	In	Type	Required	Description
`namespace`	path	enum<"profiles">	required	Namespace. Currently, only `profiles` is available.
`aggregateId`	path	string	required	Aggregate ID

Responses

Status	Description
`204`	Aggregate deleted
`4XX` `application/json`	See error message for details
`5XX` `application/json`	See error message for details

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/analytics/%7Bnamespace%7D/aggregates/%7BaggregateId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Back to all API categories

Status	Description
`200` `application/json`	A list of tags
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)

Status	Description
`200` `application/json`	Tag created
`400` `application/json`	Invalid or incomplete data
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`415` `application/json`	Unsupported Media Type

Status	Description
`200` `application/json`	Tag updated
`400` `application/json`	Invalid or incomplete data
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Tag doesn't exist or it is a global tag (not related to any workspace).
`415` `application/json`	Unsupported Media Type

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

Status	Description
`200` `application/json`	Tag assigned
`400` `application/json`	Profile not found or data malformed
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions (when PII protection is enabled, PII permissions are required in addition to the permissions listed in the method description)
`404` `application/json`	Tag not found
`415` `application/json`	Unsupported Media Type

Data Management — API Reference

Events

POST /v4/transactions — Create a transaction

Parameters

Request body (required)

Responses

Example request (cURL)

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

Parameters

Request body (required)

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Request body (required)

Responses

Example request (cURL)

POST /v4/events/registered — Profile account registered

Parameters

Request body

Responses

Example request (cURL)

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

Parameters

Request body

Responses

Example request (cURL)

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

Parameters

Request body

Responses

Example request (cURL)

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

Parameters

Request body (required)

Responses

Example request (cURL)

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

Parameters

Request body (required)

Responses

Example request (cURL)

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

Parameters

Request body (required)

Responses

Example request (cURL)

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

Parameters

Request body (required)

Responses

Example request (cURL)

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

Parameters

Request body

Responses

Example request (cURL)

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

Parameters

Request body

Responses

Example request (cURL)

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

Parameters

Request body

Responses

Example request (cURL)

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

Parameters

Request body

Responses

Example request (cURL)

`POST` `/v4/transactions` — Create a transaction

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

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

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

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

`POST` `/v4/events/registered` — Profile account registered

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`POST` `/v4/events/searched` — Search requested

`POST` `/v4/events/shared` — Content shared

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

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

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

`POST` `/v4/events/custom` — Custom event

`POST` `/v4/events/batch` — Batch send events

`GET` `/v4/server/time` — Get server time