user

Welcome to our updated API documentation! (Details here.)
We invite you to rate this page at the bottom or send feedback to docs@sailthru.com.

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 data Sailthru tracks, 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.

To get started, use the API Client Library for your preferred language, or learn how to make Sailthru API calls with curl on the API Technical Details page. When using either method, or the API Test tool, you can use this page as a reference for building calls and interpreting responses.


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,
        "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,
    }
}

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"
    },
    "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" : "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, Sailthru-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.

 

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 anonymous user, include the anonymous 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 anonymous user, include the anonymous 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
        }
}

Remove from a list:

{
    "id":"user@example.com",
    "key":"email",
    "lists":
        {
            "Active Users":0
        }
}

Optouts

Set an Opt-Out Status – none, basic, blast, or all:

{
    "id":"user@example.com",
    "optout_email":"all"
}

Opt Out of a Specific Template:

{
    "id":"user@example.com",
    "optout_templates":
    {
        "Template Name":1        
    }        
}

Opt Back In to a Specific Template:

{
    "id":"user@example.com",
    "optout_templates":
    {
        "Template Name":0        
    }        
}

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.

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"
    }
}

POST Parameters

Type Parameter Description
Required 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, Sailthru-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)
Optional 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
Optional lists Add or remove users to/from natural lists
Optional optout_email Sets email opt-out status. Valid values:

  • none
  • all
  • basic
  • blast
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 cookies The cookies parameter accepts the values of Sailthru 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 anonymous browsing data to a user profile once they are identified via login or signup.For anonymous users, the sailthru_cid cookie stores up to 16 most-recently visited URLs on your domain. When an anonymous 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}

 

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 Sailthru 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 A Sailthru 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 $

Top