user

Create users and update user profile data, including key values, custom var data, and list membership. Retrieve any user profile data - data you have added, such as var values, and tracked data, such as user activity or engagement data.

Designed for user-specific, realtime information updates and retrieval. For bulk user data requests, see the job API. Endpoint URL: https://api.sailthru.com/user

GET user profile data

Get Default Fields

Get data for a user (default fields only) by any profile key. The default key is email.

By Email

Example Call:
{
  "id":"example@sailthru.com"
}
The default key type is email, so you do not need to specify a key type here.

By Sailthru sid

Example Call:
{
  "id":"538e4ef60bbc0a58ddd84a3d",
  "key":"sid"
}

By External ID (extid)

Example Call:
{
  "id":"IDfromOtherSystem_12345",
  "key":"extid"
}

By SMS #

Example Call:
{
  "id":"+15551234567",
  "key": "sms"
}

Response

Example Response:
{
  "keys" : {
    "sid" : "57b4352f3f92a4254f3d5607",
    "cookie" : "00d7f044d22008db0ab6a6e03197310f57b4352f3f92a4254f3d56077028ecc56eba8355588a3f3592affa92",
    "email" : "example@sailthru.com"
  },
  "vars" : {
    "Var_1": "var_1_val",
    "Var_2": "var_2_val"
  },
  "lists" : {
    "Test List" : "Wed, 17 Aug 2016 05:58:07 -0400",
    "Test List 2" : "Wed, 17 Aug 2016 05:58:07 -0400"
  },
  "engagement" : "new",
  "optout_email" : "none"
}
Only default fields - keys, vars, lists, engagement, and optout status (optout_email) - are returned.

Get Specific Fields

Get data for a user by any profile key, specifying the fields you want returned in the response.

By Email Address

Example Call:
{
    "id":"example@sailthru.com",
    "key": "email",
    "fields": {
        "activity": 1,
        "device": 1,
        "engagement": 1,
        "keys": 1,
        "lifetime": 1,
        "lists": 1,
        "optout_email": 1,
        "purchase_incomplete": 1,
        "purchases": 1,
        "smart_lists": 1,
        "vars": 1
    }
}
In the fields object, include only those fields that you want returned.

Response JSON

Example Response:
{
    "activity" : {
        "signup_time" : "Wed, 17 Aug 2016 05:58:07 -0400",
        "create_time" : "Wed, 17 Aug 2016 05:58:07 -0400"
    },
    "device" : null,
    "engagement" : "new",
    "keys" : {
        "sid" : "57b4352f3f92a4254f3d5607",
        "cookie" : "00d7f044d22008db0ab6a6e03197310f57b4352f3f92a4254f3d56077028ecc56eba8355588a3f3592affa92",
        "email" : "example@sailthru.com"
    },
    "lifetime" : {
        "lifetime_message" : 7,
        "lifetime_pv" : 2,
        "lifetime_purchase" : 26,
        "lifetime_purchase_price" : 8000
    },
    "optout_email" : "none",
    "purchase_incomplete" : {
        "_id" : ObjectId('542edba038be080c5eeaefba'),
        "items" : [
            {
                "qty" : 5,
                "title" : "Water Bottle",
                "price" : 100,
                "id" : 6546,
                "url" : "http://www.google.com/something"
            }
        ],
        "price" : 500,
        "qty" : 5,
        "time" : new Date('Fri, Oct 3 2014, 1:23 pm EDT'),
        "unique_id" : "542edba038be080c5eeaefba",
        "chnl" : "online"
    },
    "purchases" : [
        {
            "price" : 100,
            "qty" : 1,
            "time" : "Wed, 30 Nov 2016 12:31:26 -0500",
            "items" : [
                {
                    "title" : "Nice Boots",
                    "id" : "id1",
                    "url" : "http://demo-product2.com",
                    "tags" : null,
                    "price" : 100,
                    "qty" : 1,
                    "vars" : null
                }
            ]
        }
    ],
    "smart_lists" : [
        "All Users",
        "Demo",
        "Smart List Training L1",
        "carnival_user",
        "hdloo",
        "nope",
        "test234",
        "tmp+",
        "tmp_multi",
        "tmp_multi_with_prime"
    ],
    "vars" : {
        "blah" : "bleh",
        "name" : "Angelica",
        "birthday_month" : "march",
        "source" : "web",
        "anniversary_date" : "today",
        "fname" : "Bob",
        "sign_up_date" : "today"
    }
}
All requested fields are returned.

GET Parameters

Type Parameter Description
Required id The key value of the user.
Optional key The key type of the 'id' value used to look up the user. The default is email. Specify one of the following if it is available as a key across your user profiles:
  • sid - The default, system-specified identifier for a user's profile
  • extid - A unique, user-specified identifier for a user's profile (only available if you enable extid lookup)
  • cookie - The Horizon cookie value, stored in sailthru_hid
  • email - The user's email address
  • sms - The user's SMS number (only available if you enable SMS)
  • fb - The user's Facebook ID (only available if you enable Facebook lookup)
  • twitter - The user's Twitter ID (only available if you enable Twitter lookup)
Optional fields An object containing key-value pairs of field names to return. Use the value of 1 to request the field. The default response consists of keysvarslists,engagement, and optout_email. For more information on each field, see the User Profile Fields Reference on this page.
Return N/A Returns data consisting of the optional fields you passed. If you do not pass fields, the default return consists of keysvarslists,engagement, and optout.
Note: For a list of recommended custom vars, see Recommended Variables.

POST to create or update user

Create User

Create a user, specifying a key. The default is email address. To add the browsing activity of a formerly unknown user, include the unknown user cookie (sailthru_cid or sailthru_content) value. You can include additional data and settings (such as list memberships, vars, and opt-outs) within this same initial call, or update the user through a subsequent call.

By Email

Example Call:
{
    "id":"user@example.com"
}
The default key type is email, so you do not need to specify a key type here.

By Other Key

Example Call:
{
    "id":"+15551234567",
    "key": "sms"
}

With Cookie Value

Example Call:
{ 
    "id": "user@example.com",
    "cookies": {
        "sailthru_cid":"U9JEVqLefidFAAAA"
    }
}

By Email with Additional Data

Example Call:
{
    "id": "user@example.com",
    "keys": {
        "extid": "0123456789",
        "sms": "+15551234567"
    },
    "lists": {
        "NaturalListNameToJoin":1,
        "NaturalListNameToLeave":0
     },
    "vars": {
        "FirstName": "Douglas",
        "LastName": "Crockford"
    }    
}

Response

Example Response:
{
    "ok" : true
}
If the user is created, you'll receive this response.

Update User

Update a user, specifying a key. The default is email address. To add the browsing activity of a formerly unknown user, include the unknown user cookie (sailthru_cid or sailthru_content) value.

Email

Example Call:
{
    "id": "user@example.com",
    "keys": {
        "email": "new_user@example.com"
    }
}
Update the user's email address. The default key type is email, so you do not need to specify a key type here (as 'key').

Keys

Example Call:
{
    "id": "user@example.com",
    "keys": {
        "extid": "1234567890"
    }
}
Adds/updates a key.

Fields

Example Call:
{
    "id": "user@example.com",
    "lists": {
        "NaturalListNameToJoin":1,
        "NaturalListNameToLeave":0
     },
    "optout_templates":{
        "Template Name":1        
    },
    "vars": {
        "gender": "male",
        "vip_level": 2,
        "anyCustomKey": "anyValue"
    },
    "optout_email": "blast"
}
Adds/updates other fields.

Request Fields

Example Call:
{
    "id":"user@example.com"
    "fields": {
        "activity": 1,
        "apps": 1,
        "apptrack": 1,
        "device": 1,
        "engagement": 1,
        "keys": 1,
        "lifetime": 1,
        "lists": 1,
        "optout_email": 1,
        "purchase_incomplete": 1,
        "purchases": 1,
        "smart_lists": 1,
        "vars": 1,
    }
}
Request user profile data to include in the response. Similar to a GET call. You must make a profile change when requesting fields using a POST call. To request fields without making a user profile change, use a GET call.

Lists

Add to a list:
{
    "id":"user@example.com",
    "key":"email",
    "lists":
        {
            "Active Users":1
        }
}
If the specified list does not exist, it will be created. Remove from a list:
{
    "id":"user@example.com",
    "key":"email",
    "lists":
        {
            "Active Users":0
        }
}

Optouts

Set an Opt-Out Status - none, basic, or all. For information on each of the opt-out statuses, see the User Opt-Out Levels documentation. Opt out of all messaging:
{
    "id":"user@example.com",
    "optout_email":"all"
}
Opt Out of marketing messaging:
{
    "id":"user@example.com",
    "optout_email":"basic"
}

Merge Profiles

Example Call:
{
    "id":"4e2879472d7acd6d97144f9e",
    "key": "sid",
    "keys":
        {
            "email":"user@example.com"
        },
    "keysconflict":"merge"
}
Merges profile of user@example.com to the profile with the specified key/value. The user profile that you are referencing with id is updated with the merged user data/keys. The other duplicate profiles are deleted. When a hardbounced user is merged into another profile (either an existing profile or one being created), the system keeps the hardbounce profile and passes all profile data to the new profile.

Response

Example Response Without Requesting Fields:
{
    "ok" : true
}
Example Response With Requested Fields:
{
    "ok" : true,
    "activity" : {
        "signup_time" : "Wed, 17 Aug 2016 05:58:07 -0400",
        "create_time" : "Wed, 17 Aug 2016 05:58:07 -0400"
    },
    "apps" : {
        "576ab289e9328b4a5c8b56faacabd25475bfbdb927ca989ef5cba4d0eefb9655d33d127dc8e01432dc01e8ca" : {
            "aid" : ObjectId('576ab289e9328b4a5c8b56fa'),
            "did" : "acabd25475bfbdb927ca989ef5cba4d0eefb9655d33d127dc8e01432dc01e8ca",
            "dt" : "iphone",
            "dv" : "4.3",
            "ov" : "9.2",
            "pav" : "1.0.1",
            "paid" : "com.sailthru.qa2",
            "e" : "prod",
            "s" : "active"
        }
    },
    "apptrack" : null,
    "device" : null,
    "engagement" : "new",
    "keys" : {
        "sid" : "57b4352f3f92a4254f3d5607",
        "cookie" : "00d7f044d22008db0ab6a6e03197310f57b4352f3f92a4254f3d56077028ecc56eba8355588a3f3592affa92",
        "email" : "user@example.com"
    },
    "lifetime" : {
        "lifetime_message" : 7,
        "lifetime_pv" : 2,
        "lifetime_purchase" : 26,
        "lifetime_purchase_price" : 8000
    },
    "optout_email" : "none",
    "purchase_incomplete" : {
        "_id" : ObjectId('542edba038be080c5eeaefba'),
        "items" : [
            {
                "qty" : 5,
                "title" : "Water Bottle",
                "price" : 100,
                "id" : 6546,
                "url" : "http://www.google.com/something"
            }
        ],
        "price" : 500,
        "qty" : 5,
        "time" : new Date('Fri, Oct 3 2014, 1:23 pm EDT'),
        "unique_id" : "542edba038be080c5eeaefba",
        "chnl" : "online"
    },
    "purchases" : [
        {
            "price" : 100,
            "qty" : 1,
            "time" : "Wed, 30 Nov 2016 12:31:26 -0500",
            "items" : [
                {
                    "title" : "Jeans",
                    "id" : "id1",
                    "url" : "http://example.com/product/jeans",
                    "tags" : null,
                    "price" : 100,
                    "qty" : 1,
                    "vars" : null
                }
            ]
        }
    ],
    "smart_lists" : [
        "All Users",
        "Recent Purchases (30 Days)",
        "VIP Level 2"
    ],
    "vars" : {
        "name" : "Angelica",
        "birthday_month" : 3,
        "source" : "facebook"
    }
}

Get ID to Cookie New or Existing User

In order to attribute user browsing sessions and the interests that they reflect to user profiles, a known user should always have a sailthru_hid cookie set in their browser. The value for a given user remains consistent and is available on the user profile under keys.cookie. This cookie is set automatically when a user clicks a link to your site in one of your emails, however if there are cases where you may otherwise identify a known user (such as a site login, form submission, or purchase), you should manually set the cookie at that time. There are two methods to accomplish this:
  • a server-side API call using this user endpoint--via the same, single call you'd use to create/update the user
  • the userSignUp() JavaScript Function, which sets the cookie automatically
If using this user API, you'll need to ensure the fields.keys value is requested which returns the user's cookie value, which you can then return to the browser to create the cookie. This process mirrors the above "Create" and "Update" methods, but ensures that you are requesting the required keys.

Simple Call

Example Call:
{
    "id" : "user@example.com",
    "fields" : {"keys":1}
}

Advanced Call

Example Call:
{
    "id" : "user@example.com",
    "keys" : {"extid": 1},
    "vars" : {"name":"Geeve Stiordano" },
    "lists" : {
       "Daily_Newsletter" : 1,
       "Weekly_Newsletter: 0
    },
    "fields":{"keys":1}
}

Response

Example Response:
{
 "keys" : {
 "sid" : "54bc3309f641915770c2be78",
 "cookie" : "fd1a088555d2c5a1e2b275c23c41762f54bc3309f641915770c2be78c7ebb371b7851106b091c9b651ed954b",
 "email" : "sgiordano@sailthru.com"
 },
 "ok" : true
}
You can then set the user's sailthru_hid cookie value using the value of vars.cookie.

POST Parameters

Note: Either id or keys must be used.
Type Parameter Description
Required, if keys isn't used id The key value to identify the user.
Optional key The key type of the 'id' value used to identify the user. The default is email. Specify one of the following:
  • sid - The default, system-specified identifier for a user's profile
  • extid - A unique, user-specified identifier for a user's profile (only available if you enable extid lookup)
  • email - The user's email address
  • sms - The user's SMS number (only available if you enable SMS)
  • fb - The user's Facebook ID (only available if you enable Facebook lookup)
  • twitter - The user's Twitter ID (only available if you enable Twitter lookup)
Required, if id isn't used keys Object to set some or all of the user keys. A hash of key names and values.
Optional keysconflict If you attempt to change keys to values that match existing keys already in the database, you create a conflict. You can specify the resolved behavior of the conflict with keysconflict. Valid values:
  • error (Default) - Returns a duplicate error if there are multiple user profiles in the database with matching keys.
  • merge - Merges multiple profiles in the database that have matching keys. The user profile that you are referencing with id is updated with the merged user data/keys. The other duplicate profiles are deleted.
Optional fields User profile fields to return with the request. For more information on each field, see the User Profile Fields Reference on this page.
Optional vars Set custom variables on the user. For a list of recommended custom vars, see Recommended Variables.
Optional lists Add or remove users to/from natural lists
Optional optout_email Sets email opt-out status. Valid values:
  • none
  • all
  • basic
Optional optout_templates Opt a user in to or out of a template. Required values:
  • Template name
  • Opt out or in
    • 1 = opt out from specified template OR
    • 0 = opt in to specified template
Optional sms_marketing_status Sets SMS opt-in status for marketing messages. Valid values:
  • opt-in
  • opt-out
Optional sms_transactional_status Sets SMS opt-in status for transactional messages. Valid values:
  • opt-in
  • opt-out
Optional (deprecated) optout_sms_status Sets SMS opt-in status for marketing messages. Valid values:
  • opt-in
  • opt-out
This is a deprecated parameter. Please use sms_marketing_status or sms_transactional_status to set the consent status for a profile.
Optional cookies The cookies parameter accepts the values of system cookies in order to convert the stored browser session data into user profile data. For instance, the value of the sailthru_cid or sailthru_content cookie can be passed to add unknown user browsing data to a user profile once they are identified via login or signup. For unknown users, the sailthru_cid cookie stores up to 16 most-recently visited URLs on your domain. When an unknown user converts (signs up or signs in), the collected data is used to build a user profile interest data and content recommendations.
Return N/A POST mode returns {"ok":true}
 

DELETE a user

Deleting a user permanently removes that user's profile, including any associated records such as purchase and pageview information.

Note: The system records aggregate data, like total purchases, revenue, pageviews, etc. for an account, and also records that information on a user level. After deleting a user, the summation of individual records may not match the aggregates, since the individual record has been deleted. The aggregate values will still include data from views and purchases by users before they were deleted from Sailthru. Deleting a user through the API requires your API Key and Secret. Identify the user by any supported id including sid, email, extid, SMS, twitter, or fb.

By Email

Example Call:
{
  "id":"example@sailthru.com"
}
The default key type is email, so you do not need to specify a key type here.

By sid

Example Call:
{
  "id":"538e4ef60bbc0a58ddd84a3d",
  "key":"sid"
}

By External ID (extid)

Example Call:
{
  "id":"IDfromOtherSystem_12345",
  "key":"extid"
}

By SMS #

Example Call:
{
  "id":"+15551234567",
  "key": "sms"
}

Response

Example Response:
{
"ok": true
}
Note: If you use Mobile and need to fully delete a profile or profiles, first use the Mobile API to erase the device(s) and then use the API to delete the profile(s).  If you wish to use the Mobile UI, go to the Settings section. From there, go to Logs (Devices) to search for and select the user(s) or device(s) by their unique identifier. To erase the user/device, select Erase from the menu in the top right corner of the screen.

DELETE Parameters

Type Parameter Description
Required id The key value of the user.
Optional key The key type of the 'id' value used to delete the user. The default is email. Specify one of the following if it is available as a key across your user profiles:
  • sid - The default, system-specified identifier for a user's profile
  • extid - A unique, user-specified identifier for a user's profile (only available if you enable extid lookup)
  • cookie - The Horizon cookie value, stored in sailthru_hid
  • email - The user's email address
  • sms - The user's SMS number (only available if you enable SMS)
  • fb - The user's Facebook ID (only available if you enable Facebook lookup)
  • twitter - The user's Twitter ID (only available if you enable Twitter lookup)

User Profile Fields Reference

Parameter Description
activity View the following recent user activity:
  • open_time - The time of the user's most recent email open
  • click_time - The time of the user's most recent click
  • view_time - The time of the user's most recent view
  • login_time - The time of the user's most recent log in
  • create_time - The time of the user's profile creation
  • signup_time - The time the user was added to their first list
engagement The user's current engagement level
keys A list of currently set keys on the user
lists The normal lists the user is signed up for, with signup dates
optout_email The current email optout status of the user
smart_lists The current smart lists the user is part of
vars The custom vars set on the user
purchases A list of purchased items the user purchased. Modify the Purchases count to change the number of items returned. For example: "2" would return 2 items.
device Receive the user's most used device when opening an email
purchase_incomplete This allows you to pull all of the details on a user's last incomplete purchase
lifetime
  • lifetime message: how many total emails have we sent to the user
  • lifetime_pv: pageviews a user has accumulated
  • lifetime_click: total email clicks
  • lifetime_purchased: number of times a user has made a purchase
  • lifetime_purchased_price: total amount a user has spent in lifetime with the brand
 

Additional Examples

POST - Set The Email Address Of User With ID "4e2879472d7acd6d97144f9e" to "example@example.com"
{
    "id":"4e2879472d7acd6d97144f9e",
    "key":"sid",
    "keys":
        {
            "email":"example@example.com"
        }
}
POST - Change An Email Address Of A User By Referencing An ID (sid), Using The "keysconflict" Parameter
{
    "id":"4e2879472d7acd6d97144f9e",
    "key":"sid",
    "keys":
        {
            "email":"example@example.com"
        },
    "keysconflict":"merge"
}
POST - Change An Email Address Using The "keysconflict" Parameter
{
    "id":"emailtobeoverwritten@example.com",
    "key":"email",
    "keysconflict":"merge",
    "keys":
        {
            "email":"newemail@example.com"
        }
}
POST - Change An Existing SMS Number Using The "keysconflict" Parameter This changes the existing id to the new sms key.
{
    "id":"9175551212",
    "key":"sms",
    "keys":{"sms":"7775551212"},
    "keysconflict":"merge"
}

Error Codes

GET

HTTP Status

Error Code

Error Message

Notes

400

2

Missing required parameter: id

Required Parameters : id

400

99

Your account is not enabled for sms/twitter/fb lookup

Account must be enabled to use additional keys

400

99

User not found with {KEY}:

200

99

Invalid {KEY}

Key failed validation

200

11

Invalid email:

Email is banned

POST

HTTP Status

Error Code

Error Message

Notes

400

99

Your account is not enabled for sms/twitter/fb lookup

Account must be enabled to use additional keys

200

99

Invalid {KEY}

Key failed validation

200

11

Invalid email: {EMAIL}

Email is banned

400

99

Too many vars, max is 1,000

400

99

There is already a user with {KEY} {VALUE}

Occurs when updating a user to another key value that belongs to another user

400

99

You may not change the sid/cookie key

400

99

You do not have support for the {KEY} key

400

99

User not found with sid: {SID}

Error thrown when looking up user by SID that can not be found

403

99

You may not subscribe a user to a smart list ({SMART_LIST_NAME})

Can not specify a smart list in the lists field

400

99

List name cannot contain a $ character 111$ {SMART_LIST_NAME}

Lists cannot contain $

400

99

Invalid JSON provided

 

DELETE

HTTP Status

Error Code

Error Message

Notes

400

99

Bad request - There is a problem with the parameters of this request

400

99

Your account is not enabled for {KEY} lookup

Account must be enabled to use additional keys

404

99

User not found with {KEY} : {ID}

500

99

There was an error processing your request.

Contact us

Top