Customer profile management

When a customer interacts with your content for the first time, you can create a profile in the database. This profile may only be identified by an ID - such a profile is anonymous (has no personal data). If a user provides their email, for example by signing up to a newsletter, they are recognized.

A profile is also created when a customer registers an account. If a customer profile with the same email already exists at the time of registration, the created account becomes connected to that profile and the data is merged.

The endpoints described in this article operate on profiles regardless of those profiles’ relation to registered accounts.

Creating profiles

Method reference available here.

The minimum data required to create a customer profile is one of the following identifiers:

  • email
  • phone
  • uuid
  • customId

For additional fields that you can send, see the reference documentation.

curl --location --request \
POST 'https://api.synerise.com/v4/clients' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJh...8MltQ' \
--data-raw '{
   "email": "sampleclient@synerise.com"
}'

Result: The response is HTTP 202 with no content. A profile is created, some properties are generated automatically or receive placeholders. See the response in Retrieving a single profile.

Retrieving a single profile

Method reference available here.

You can retrieve a single profile from the database by providing one of the following identifiers:

  • email
  • phone
  • uuid
  • customId

The following request retrieves the data of the customer created in Creating a customer profile:

curl --location --request \
GET 'api.synerise.com/v4/clients/by-email/sampleclient@synerise.com' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJhb...hjM' \

The response is the customer data. During profile creation, the only provided property was the email (see curl example in Creating profiles - the other properties are generated automatically or receive placeholder values.

{
    "previousClients": [],
    "clientId": 2149203825,
    "email": "sampleclient@synerise.com",
    "phone": null,
    "customId": null,
    "uuid": "24f539a0-d257-11ea-92f0-23c0f0aec77f",
    "firstName": "Sampleclient",
    "lastName": null,
    "displayName": null,
    "company": null,
    "address": null,
    "city": null,
    "province": null,
    "zipCode": null,
    "countryCode": null,
    "birthDate": null,
    "lastActivityDate": "2020-07-30T11:23:51Z",
    "sex": "NOT_SPECIFIED",
    "avatarUrl": "https://www.gravatar.com/avatar/2b13fb10fcb2ff3327a41c3c5dd3d2cd?s=100&r=g&d=blank",
    "anonymous": false,
    "agreements": {
        "email": false,
        "sms": false,
        "push": false,
        "webPush": false,
        "bluetooth": false,
        "rfid": false,
        "wifi": false
    },
    "attributes": {
        "eventCreateTime": "2020-07-30T11:23:46.092Z",
        "correlationId": "D57HkYUzRRu2ImZmjNg-Iw"
    },
    "tags": []
}

Listing profiles

Method reference available here.

This method allows you to list customer profiles from the database. The results can be filtered (see method reference).

The maximum number of retrieved entries is 10 000.

curl --location --request \
GET 'https://api.synerise.com/crm/v1/list' \
--header 'Authorization: Bearer eyJh...8MltQ' \

The response is a list of profiles.

Updating profiles

Method reference available:

You can update the customer profile. When sending the request, include only the fields that you want to update. 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). Empty strings are not accepted.

The following example updates the customer’s name and surname:

curl --location --request \
POST 'api.synerise.com/v4/clients/by-email/sampleclient@synerise.com' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJhb...Jes' \
--data-raw '{
    "firstName": "John",
    "lastName": "Smith"
}'

Result: The response is HTTP 202 with no content. The profile data is updated.

Deleting profiles

Method reference available:

You can delete a profile.

curl --location --request \
DELETE 'api.synerise.com/v4/clients/2149203825' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJhbG...DVDg2Udg' \

Result: The response is HTTP 202 with no content. The profile is deleted.

Creating/updating multiple profiles

Method reference available here.

Customer profiles can be added or updated in batch. When you perform this operation, existing profiles are updated, and data that does not match any profiles results in creating new profiles.

When sending the request, include only the fields that you want to update. 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). Empty strings are not accepted.

The following request creates two new profiles and updates the firstName field of the customer created in Creating profiles:

curl --location --request \
POST 'api.synerise.com/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJhb...EGRXjc' \
--data-raw '[
   {
      "email": "newclient@synerise.com"
   },
   {
      "customId": "newClientCustomId"
   },
   {
      "email": "sampleclient@synerise.com",
      "firstName": "Michael"
   }
]'

Result: The response is HTTP 202 with co content. The operation is queued.

Note: Completing a batch operation may take some time, depending on request size and server load.

Merging profiles

You can merge multiple profiles into one.

Important: By default, only profiles with an email are recognized. A profile with a customId but no email is treated as anonymous. To change this behavior, see Setting non-unique emails.

By UUID and customId

Merging is performed by using the batch create/update endpoint.

The request body is an array of objects. Each object is a pair of profiles to merge. One profile is identified by UUID, the other by custom ID.

This request merges two anonymous profiles into one: 

curl --location --request POST 'api.synerise.com/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJh...y4' \
--data-raw '[
   {
      "uuid": "88f40b29-5ba8-437b-ba9d-6d3b99dff80f",
      "customId": "lue42"
   }
]'

Important: If you want to merge more accounts in a single request, send more objects. Each object is treated as a separate pair, so if you send 3 pairs, the result is 3 accounts, not 1 account merged from 6.

By UUID and email

WARNING: If you enabled the non-unique emails feature, this method is NOT recommended.

Merging is performed by using the batch create/update endpoint.

The request body is an array of objects. Each object is a pair of profiles to merge. The anonymous profile is identified by UUID, the recognized one by email.

This request merges an anonymous profile (identified by UUID) into a recognized one (identified by email).
The merged profile receives the UUID of the anonymous profile. 

curl --location --request POST 'api.synerise.com/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJh...y4' \
--data-raw '[
   {
      "uuid": "88f40b29-5ba8-437b-ba9d-6d3b99dff80f",
      "email": "sampleclient@synerise.com"
   }
]'

Important: If you want to merge more accounts in a single request, send more objects. Each object is treated as a separate pair, so if you send 3 pairs, the result is 3 accounts, not 1 account merged from 6.

By customIds

Merging recognized customers is done with an endpoint set up specifically for that.

Only custom IDs can be used for this operation.

WARNING:
  • This operation is irreversible. Use it carefully.
  • The source accounts are deleted.
  • Do not merge more than 20 accounts at once.

The following request merges profiles lue42 and mjz84 into a third profile: tla114. lue42 and mjz84 are permanently deleted! 

curl --location --request POST \
'api.synerise.com/v4/clients/merge/from/custom-ids/lue42,mjz84/to/custom-id/tla114' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJh...ey4'

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.