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:

Copy

{
  "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:

Copy

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

By External ID (extid)

Example Call:

Copy

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

By SMS #

Example Call:

Copy

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

Response

Example Response:

Copy

{
  "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:

Copy

{
    "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:

Copy

{
    "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 `keys`, `vars`, `lists`,`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 `keys`, `vars`, `lists`,`engagement`, and `optout`.

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:

Copy

{
    "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:

Copy

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

With Cookie Value

Example Call:

Copy

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

By Email with Additional Data

Example Call:

Copy

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

Response

Example Response:

Copy

{
    "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:

Copy

{
    "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:

Copy

{
    "id": "user@example.com",
    "keys": {
        "extid": "1234567890"    }
}

Adds/updates a key.

Note: If you are adding an email key to an existing user profile, use one of the profile's existing keys as the ID.

Fields

Example Call:

Copy

{
    "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:

Copy

{
    "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:

Copy

{
    "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:

Copy

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

Optouts

Set an Opt-Out Status - none, basic, or all.

Opt out of all messaging:

Copy

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

Opt Out of marketing messaging:

Copy

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

Merge Profiles

Example Call:

Copy

{
    "id":"4e2879472d7acd6d97144f9e",
    "key": "sid",
    "keys":
        {
            "email":"user@example.com"        },
    "keysconflict":"merge"}

Merges the profile of user@example.com with the profile with the specified key/value. The user profile that you are referencing with an Engage by Sailthruid 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:

Copy

{
    "ok" : true
}

Example Response With Requested Fields:

Copy

{
    "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:

Copy

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

Advanced Call

Example Call:

Copy

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

Response

Example Response:

Copy

{
 "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.

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:

Copy

{
  "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:

Copy

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

By External ID (extid)

Example Call:

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

By SMS #

Example Call:

Copy

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

Response

Example Response:

Copy

{
"ok": true
}

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"

Copy

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

Copy

{
    "id":"4e2879472d7acd6d97144f9e",
    "key":"sid",
    "keys":
        {
            "email":"example@example.com"        },
    "keysconflict":"merge"}

POST - Change An Email Address Using The "keysconflict" Parameter

Copy

{
    "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.

Copy

{
    "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.