Identify Api

Herogi CDP provides Identify API to collect your users data. To able to use segments and other campaign features fully you need to start sending your users metadata to Herogi.

Before we discuss how to send/collect user data let’s take a close look what type of attributes available on Herogi User entity

User Object

Your customer’s data defined as User within Herogi and each User has multiple core attributes and some custom attributes.

User Attributes

User Attributes is essentially key/value pair of data associated with any User object. All these attributes become available in Campaign / Complex Scenario context which gives you huge personalization capabilities. So it’s important to send as much as data possible to benefit from power features.

Attributes Data Type Required Example Description
hgid STRING NO 6ef91c7c-3363-4agh-1b0c-10e2tb537b71 Internal Herogi identifier, if you want to update use set, if you don’t provide it’ll generate one
externalUserId STRING NO user123 [Unique] External user identifier such user id in your system or email, if you know it attach it so that you can associate your users in Herogi easily
email STRING NO Email address of user, email campaigns will use this
mobileNo STRING NO +901111111111 Mobile phone number of user, sms campaigns will use this
firsname STRING NO John Firstname of user
lastname STRING NO Wick Lastname of user
gender STRING NO MALE Gender of user. Available Options: MALE, FEMALE, OTHER
language STRING NO EN Language of user. ISO Alpha 2 Code
country STRING NO US Country of user. ISO Alpha 2 Code
city STRING NO Wick City of user
currentLocation STRING NO ”{"latitude":12.1218024,"longitude":100.3194508}” Coordinates of user, this can be useful in location sensitive campaigns
timezone STRING NO America/New_York User timezone, this can be used timing campaigns properly, E.g send a push message in user’s timezone 3pm
facebookId STRING NO 12345678 Facebook identifier
twitterId STRING NO elonmusk Twitter username
lineId STRING NO a123456 Line username
customAttributes STRING NO ”{"weddingBudget": ["LUXURY”, "PREMIUM"], ..}” JSON string of custom attributes, this will be only stored if it’s created on Audience Dashboard first
emailOptin STRING NO OPTIN User grant for email. Available Options: OPTIN, OPTOUT. Default value is OPTIN
smsOptin STRING NO OPTIN User grant for sms. Available Options: OPTIN, OPTOUT. Default value is OPTIN
pushOptin STRING NO OPTIN User grant for push. Available Options: OPTIN, OPTOUT. Default value is OPTIN
webPushOptin STRING NO OPTIN User grant for webpush notification. Available Options: OPTIN, OPTOUT. Default value is OPTIN
locationOptin STRING NO OPTIN User grant for location sensitive op. Available Options: OPTIN, OPTOUT. Default value is OPTIN

Create/Update User

There are multiple ways of managing users. If you’re using a backend application and you want to manage how and when to add users then better to use our Rest api to connect. Alternative way is you can use our javascript library and add your web application which collects all this automatically with minimal effort.

Base URL

All URLs referenced in the documentation have the following base;

Javascript SDK: herogi.min.js

Add first minimized js file to your website.

   <script src=""></script>

This will enable herogi object in the javascript scope which you can access and use

Now let’s identify users;

//Get your app id and app secret from Herogi Dashboard
//If you want to collect user location set third parameter true, this will ask user in browser to allow location data
herogi.init("APPID","APPSECRET", true);

//If you don't know anything about user you can create initial empty user like this, it will create hgid and persist in browser which later identify just updates
herogi.identify(null, null,null, function (res, d) {

You can also set user attributes, custom user attributes and preferences when you call herogi.identify, here is an example;

  {"firtname" : "John", "lastname" : "Wick"}, 
  {"weddingBudget" : ["LUXURY", "PREMIUM"}
  {"emailOptin" : "OPTIN"}, function (res, d) {

Finally if you identify that user has an internal identifier in your system; you can explicity set it on Herogi, this is most of the time when you actually login a customer and you know who she is in your system

herogi.identify("user1234567" //User id or unique identifier from your system
  {"firtname" : "John", "lastname" : "Wick"}, 
  {"weddingBudget" : ["LUXURY", "PREMIUM"}
  {"emailOptin" : "OPTIN"}, function (res, d) {

External identifier helps Herogi to associate your user with Herogi user, if there is an existing user defined on Herogi with same external id Herogi will merge this data with the other record on our database, local hgid stored in previous sessions will be overriden by existing hgid coming from database

herogi.identify Documentation

herogi.identify(externalId, userAttributes, customAttributes, preferences, callback)

If you skip externalId all parameters can shift to left by 1

herogi.identify(userAttributes, customAttributes, preferences, callback)

Param Data Type Required Example Description
externalId STRING NO 123456 Unique userid, email from your system
userAttributes OBJECT NO {“GENDER” : “FEMALE”} Key-value attribute objects
customAttributes OBJECT NO {“key” : “val”} Key-value custom attributes objects
preferences OBJECT NO {“smsOptin” : “OPT-IN”} Key-value preference objects
callback FUNC NO function(status, err) Callaback function to get result of identify operation

POST /v1/identify

  • curl --location --request POST '' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic AUTHKEY' \
    --data-raw '{       
            "city": "Bangkok",
            "mobileNo" : "+90111111111",
            "email": "",
            "firstname": "John",
            "lastname" : "Wick",
            "externalUserId" : "",
            "country" : "EN",
            "language" : "EN",
            "timezone" : "Europe/Moscow",
            "hgid" : "6ef91c7c-3363-4agh-1b0c-10e2tb537b71"
  • <?php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => '',
      CURLOPT_POSTFIELDS =>'{       
        "city": "Bangkok",
            "mobileNo" : "+90111111111",
            "email": "",
            "firstname": "John",
            "lastname" : "Wick",
            "externalUserId" : "",
            "country" : "US",
            "language" : "EN",
            "timezone" : "Europe/Moscow",
            "hgid" : "6ef91c7c-3363-4agh-1b0c-10e2tb537b71"
      CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Authorization: Basic AUTHKEY'
    $response = curl_exec($curl);
    echo $response;
  • var https = require('follow-redirects').https;
    var fs = require('fs');
    var options = {
      'method': 'POST',
      'hostname': '',
      'path': '/v1/identify',
      'headers': {
        'Content-Type': 'application/json',
        'Authorization': 'Basic AUTHKEY'
      'maxRedirects': 20
    var req = https.request(options, function (res) {
      var chunks = [];
      res.on("data", function (chunk) {
      res.on("end", function (chunk) {
        var body = Buffer.concat(chunks);
      res.on("error", function (error) {
    var postData = JSON.stringify({"city":"Bangkok","mobileNo":"+90111111111","email":"","firstname":"John","lastname":"Wick","externalUserId":"","country":"US","language":"EN","timezone":"Europe/Moscow","hgid":"6ef91c7c-3363-4agh-1b0c-10e2tb537b71"});