Documentation Powered by Redocly

Asset Management (May 9, 2023 9:11:27 AM)

Download OpenAPI specification:Download

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

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

Authentication

JWT

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

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

Remember to include a space between Bearer and the token.

The token is valid for one hour (unless configured differently). You can request a refreshed key for the session by using the auth/refresh endpoint before the current token expires.

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

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

TrackerKey

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

Security Scheme Type API Key
Query parameter name: token

Authorization

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

Refresh a Profile token

Retrieve a refreshed JWT Token to prolong the session.

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

  • API consumers who can use this method: Profile (formerly client), Anonymous profile (formerly client)

  • This method does not require a Synerise authorization token.

Authorizations:
JWT
    Request Body schema: application/json
    apiKey
    required
    string

    Profile API key

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "token": "eyJhbGciOiinvalidI6IkFQSSIsInJsbSI6ImNsaWVudCIsImN0ZCI6MTUyODM1NTgzMjEzOCwiZW1sIjoia3J6eXN6dG9mLmN6ZXJlcGFrQGdtYWlsLmNvbSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo1OTQsImNsSWQiOjUyNTQ0NjU3NCwinvalidx2XwJp-QBZ94d_EEKf41KtDCE33KhP_vTAYrs-JzbnIHgKRvG6ZRwsNOL8OTnbfbUZH4XYaqBB_tZTPPKfzHutP6GEGp7PLtu2E92JbChkVyrn8VCQ5v4z2e1-zsdgbmWcQk2g9RydaydO6NYO55suT3Hz2ZRv0AYLsG8rM1biZGdREWx9OaknVVuIo2ivehBiukL7VQ6Bu8ugjep3mn-z666a-nCMh6ZuASiQ6Geq0NSWmdDQIoCa5Hg44KzMfGRlCR2uKBXeHTD0SkwJ1VJM0sHNKwSfMXKpaX8OJ5wUJpgCzDzQwKVgxgWFp4eO_sbcvxWrpI7W0lfdCy1WKirnZ6Uh3uJ06v97GQDAQqVgBZFEpS47MrGZhTNuAG4ZbfYO7yyxVO8AHQbEC-UvZ-8DC1XZjvQ6S1uNqQIlVGcthnrxg8K6vKVhNzu6ifQI0bbsCl8bGsKkXOEK1pKR3ekckcSjNeeY2LrcdXs8F2gtkm0TjXU"
    }

    Authenticate as Profile

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

    • This method does not require a Synerise authorization token.
    Request Body schema: application/json
    apiKey
    required
    string

    Profile API key

    identityProvider
    required
    string
    Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN"

    The identity provider.

    identityProviderToken
    string

    Third-party authentication token used to authenticate with the Identity Provider. Required if identityProvider is different than SYNERISE.

    email
    string

    Profile email. Required if identityProvider is SYNERISE and email is the unique identifier (default setting).

    customId
    any

    Profile customId. Required if identityProvider is SYNERISE and customId is the unique identifier (see https://help.synerise.com/docs/settings/configuration/non-unique-emails/).

    password
    string

    Profile password. Required if identityProvider is SYNERISE.

    uuid
    string

    Profile UUID. Required if identityProvider is SYNERISE.

    deviceId
    string

    Unique Android or iOS device ID

    object

    This object contains the marketing agreements of the Profile.

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

    object

    This object contains custom attributes (with any names).

    WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored.

    Click to expand the list of reserved attributes email
    clientId
    phone
    customId
    uuid
    firstName
    lastName
    displayName
    company
    address
    city
    province
    zipCode
    countryCode
    birthDate
    sex
    avatarUrl
    anonymous
    agreements
    tags
    businessProfileId
    time
    ip
    source
    newsletter_agreement
    custom_identify
    firstname
    lastname
    created
    updated
    last_activity_date
    birthdate
    external_avatar_url
    displayname
    receive_smses
    receive_push_messages
    receive_webpush_messages
    receive_btooth_messages
    receive_rfid_messages
    receive_wifi_messages
    confirmation_hash
    ownerId
    zipCode
    anonymous_type
    country_id
    geo_loc_city
    geo_loc_country
    geo_loc_as
    geo_loc_country_code
    geo_loc_isp
    geo_loc_lat
    geo_loc_lon
    geo_loc_org
    geo_loc_query
    geo_loc_region
    geo_loc_region_name
    geo_loc_status
    geo_loc_timezone
    geo_loc_zip
    club_card_id
    type
    confirmed
    facebookId
    status
    tags
    Array of strings

    Tags can be used to group profiles.

    Responses

    Request samples

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

    Response samples

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

    Authenticate as Profile (conditional)

    Obtain a new JWT token for a Profile.

    • If the account does not exist, an account is not created.

    • If any additional conditions are required for logging in, the response is HTTP200 and lists the conditions.

    • Note that using this endpoint requires authenticating as an anonymous Profile first.

    • This method does not require a Synerise authorization token.

    Authorizations:
    JWT
      Request Body schema: application/json
      apiKey
      required
      string

      Profile API key

      identityProvider
      required
      string
      Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN"

      The identity provider.

      identityProviderToken
      string

      Third-party authentication token used to authenticate with the Identity Provider. Required if identityProvider is different than SYNERISE.

      email
      string

      Profile email. Required if identityProvider is SYNERISE and email is the unique identifier (default setting).

      customId
      any

      Profile customId. Required if identityProvider is SYNERISE and customId is the unique identifier (see https://help.synerise.com/docs/settings/configuration/non-unique-emails/).

      password
      string

      Profile password. Required if identityProvider is SYNERISE.

      uuid
      string

      Profile UUID. Required if identityProvider is SYNERISE.

      deviceId
      string

      Unique Android or iOS device ID

      object

      This object contains the marketing agreements of the Profile.

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

      object

      This object contains custom attributes (with any names).

      WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored.

      Click to expand the list of reserved attributes email
      clientId
      phone
      customId
      uuid
      firstName
      lastName
      displayName
      company
      address
      city
      province
      zipCode
      countryCode
      birthDate
      sex
      avatarUrl
      anonymous
      agreements
      tags
      businessProfileId
      time
      ip
      source
      newsletter_agreement
      custom_identify
      firstname
      lastname
      created
      updated
      last_activity_date
      birthdate
      external_avatar_url
      displayname
      receive_smses
      receive_push_messages
      receive_webpush_messages
      receive_btooth_messages
      receive_rfid_messages
      receive_wifi_messages
      confirmation_hash
      ownerId
      zipCode
      anonymous_type
      country_id
      geo_loc_city
      geo_loc_country
      geo_loc_as
      geo_loc_country_code
      geo_loc_isp
      geo_loc_lat
      geo_loc_lon
      geo_loc_org
      geo_loc_query
      geo_loc_region
      geo_loc_region_name
      geo_loc_status
      geo_loc_timezone
      geo_loc_zip
      club_card_id
      type
      confirmed
      facebookId
      status
      tags
      Array of strings

      Tags can be used to group profiles.

      Responses

      Request samples

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

      Response samples

      Content type
      application/json
      {
      • "conditions": [
        ],
      • "status": "SUCCESS",
      • "token": "string"
      }

      Authenticate anonymously

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

      • This method does not require a Synerise authorization token.
      Request Body schema: application/json
      apiKey
      string

      Profile API key (same as for Profile login)

      deviceId
      string

      Unique Android or iOS device ID