User API

Elizabeth

October 12, 2017 22:34

Blueshift hosts 360 degree user profile for each of your users to represent all of their demographic, behavioral and engagement activity. Blueshift merges logged-out activity with logged-in activity allowing for richer user profile. In addition to feed uploads we support REST APIs to create, update or retrieve user information. You will need a “user-access API key” which can be obtained by contacting support@blueshift.com

User Attributes
Create/Update User
Get User
Find User
Bulk User Create
Forget User
Unforget User
Delete User
Merge User
Error Codes & Responses

User Attributes

Attribute	Email
email	Email address of user, identifies a user uniquely.
customer_id	Customer id for this user in your database, identifies a user uniquely.
firstname	User first name (optional)
lastname	User last name (optional)
gender	User's gender (optional): male, female or unknown
joined_at	Date user joined (optional) in ISO-8601 format
facebook_id	User’s Facebook id (optional)
unsubscribed	User’s subscription status (optional) boolean. Set to true - if user has unsubscribed from mailing list
unsubscribed_at	Date when user unsubscribed in ISO-8601 format
email_hard_bounced	Automatically updated when a hard bounce occurs (true or false)
email_spam_reported	Automatically updated when a user marks your email as spam, via the ISP (true or false)
phone_number	User's phone number including ISD code. Used for SMS messaging (optional)
device_ids	Mobile device identifiers (optional)
device_tokens	Mobile device tokens used for Push messaging (optional)
birth_year	User's birth year (optional) Ex: 2001
birth_month	User's birth month (optional) Ex: 6
birth_dayofmonth	User's birth day (optional) Ex: 21
last_device_token	Most recent device token sent from your mobile app
last_location_geo_longitude	Last known geo longitude of the user
last_location_geo_latitude	Last known geo latitude of the user
custom attribute (create your own)	You may pass any other attribute, and it would get saved on the user. Ex: membership_level, loyalty_points, etc

Custom Attributes:

Blueshift allows you to send custom attributes about your customers. You can use this attributes to filter your user's during segmentation. Please use the correct data type when pushing the custom attributes as data type determine's how you can filter.

Please follow the correct JSON Data Types when creating custom attributes, data type you use determines how you can filter in the segment tab.

Data Type	Description	Sample Values
Boolean	Values in JSON can be true/false.	{ "is_premium_member": true }
Strings	Strings in JSON must be written in double quotes.	{name: "John" }
Integer	Numbers in JSON must be an integer. We would recommend using strings unless you want to do comparison operator's (like greater than or less than) on these attributes	{ "age": 30 }
Decimal	Numbers in JSON must be a floating point. We would recommend using strings unless you want to do comparison operator's (like greater than or less than) on these attributes	{ "rating": 4.5 }
Dates	Dates must be ISO8601 format	{ "signed_on": "2017-07-13T17:44:46Z" }
Arrays	Values in JSON can be arrays.	{ preferences: [ "fiction", "local" ] }
Nested Objects	Values in JSON can be nested objects. Please contact Blueshift support to discuss data design before you upload nested json objects.	{ "plan": { "name":"premium", "end_at": "2017-07-13T17:44:46Z" } }

Create / Update User

We recommend you to limit the user api calls to 50 requests/second

cURL

 curl  -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"firstname":"Mike","lastname":"Doel","customer_id":"12345","email":"test_api_user@getblueshift.com"}' -u <USER_API_KEY>:  https://api.getblueshift.com/api/v1/customers

Returns

JSON

{
    "customer": {
        "email": "test_api_user@getblueshift.com",
        "firstname": "Mike",
        "gender": "male",
        "lastname": "Doel",
        "customer_id": "1234",
        "uuid": "06743da2-9589-4c01-afda-e3d85e487fa7"
    }
}

Get User

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X GET -u <USER_API_KEY>: https://api.getblueshift.com/api/v1/customers/06743da2-9589-4c01-afda-e3d85e487fa7

Returns:

JSON

{
    "customer": {
        "activated_at": "2015-03-16T16:57:04.535Z",
        "created_at": "2015-03-15T16:57:04.535Z",
        "custom_attributes": {},
        "customer_id": "21331",
        "device_ids": [],
        "device_tokens": [],
        "email": "testuser@getblueshift.com",
        "email_hash": "e169b640b9ceda26ce4c3d8a919eb42c",
        "facebook_id": null,
        "first_lp_url": null,
        "first_referrer": null,
        "first_utm_campaign": null,
        "first_utm_content": null,
        "first_utm_medium": null,
        "first_utm_source": null,
        "first_utm_term": null,
        "firstname": "Jane",
        "gender": "female",
        "joined_at": "2015-03-15T16:57:04.528Z",
        "last_browser_platform": "Mac OS X",
        "last_browser_type": "Chrome",
        "last_browser_version": "30.0",
        "last_ip": "201.33.19.3",
        "last_location_city": "San Francisco",
        "last_location_country": "USA",
        "last_location_country_code": "US",
        "last_location_geo_latitude": null,
        "last_location_geo_longitude": null,
        "last_location_pin_code": "94536",
        "last_location_state": "California",
        "last_location_timezone": "Pacific/Los_Angeles",
        "last_lp_url": "http://site.com",
        "last_pageview_url": null,
        "last_purchase_at": "2015-03-16T16:57:04.535Z",
        "last_referrer": null,
        "last_send_at": "2015-03-17T16:57:04.535Z",
        "last_utm_campaign": null,
        "last_utm_content": null,
        "last_utm_medium": null,
        "last_utm_source": null,
        "last_utm_term": null,
        "last_visit_at": null,
        "lastname": "Doe",
        "lifetime_orders": 1,
        "lifetime_revenue": 490.0,
        "lifetime_visits": 0,
        "opt_out_of_ads": false,
        "opted_out_of_ads_at": null,
        "phone_number": null,
        "predictive_engagement_percentile": 78,
        "predictive_purchase_intent_percentile": 86,
        "predictive_retention_percentile": 70,
        "session_last_activity_at": "2015-03-16T16:57:04.535Z",
        "subscribed_at": null,
        "unsubscribed": false,
        "unsubscribed_at": null,
        "updated_at": "2015-03-16T16:57:04.583Z",
        "uuid": "1ebe515d-4ecb-4c1c-8a31-33e27c92a114"
    }
}

Find User

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X GET -u <USER_API_KEY>: https://api.getblueshift.com/api/v1/customers?email=test_api_user@getblueshift.com

Returns:

JSON

{
    "customers": [
        {
        "activated_at": "2015-03-16T16:57:04.535Z",
        "created_at": "2015-03-15T16:57:04.535Z",
        "custom_attributes": {},
        "customer_id": "21331",
        "device_ids": [],
        "device_tokens": [],
        "email": "testuser@getblueshift.com",
        "email_hash": "e169b640b9ceda26ce4c3d8a919eb42c",
        "facebook_id": null,
        "first_lp_url": null,
        "first_referrer": null,
        "first_utm_campaign": null,
        "first_utm_content": null,
        "first_utm_medium": null,
        "first_utm_source": null,
        "first_utm_term": null,
        "firstname": "Jane",
        "gender": "female",
        "joined_at": "2015-03-15T16:57:04.528Z",
        "last_browser_platform": "Mac OS X",
        "last_browser_type": "Chrome",
        "last_browser_version": "30.0",
        "last_ip": "201.33.19.3",
        "last_location_city": "San Francisco",
        "last_location_country": "USA",
        "last_location_country_code": "US",
        "last_location_geo_latitude": null,
        "last_location_geo_longitude": null,
        "last_location_pin_code": "94536",
        "last_location_state": "California",
        "last_location_timezone": "Pacific/Los_Angeles",
        "last_lp_url": "http://site.com",
        "last_pageview_url": null,
        "last_purchase_at": "2015-03-16T16:57:04.535Z",
        "last_referrer": null,
        "last_send_at": "2015-03-17T16:57:04.535Z",
        "last_utm_campaign": null,
        "last_utm_content": null,
        "last_utm_medium": null,
        "last_utm_source": null,
        "last_utm_term": null,
        "last_visit_at": null,
        "lastname": "Doe",
        "lifetime_orders": 1,
        "lifetime_revenue": 490.0,
        "lifetime_visits": 0,
        "opt_out_of_ads": false,
        "opted_out_of_ads_at": null,
        "phone_number": null,
        "predictive_engagement_percentile": 78,
        "predictive_purchase_intent_percentile": 86,
        "predictive_retention_percentile": 70,
        "session_last_activity_at": "2015-03-16T16:57:04.535Z",
        "subscribed_at": null,
        "unsubscribed": false,
        "unsubscribed_at": null,
        "updated_at": "2015-03-16T16:57:04.583Z",
        "uuid": "1ebe515d-4ecb-4c1c-8a31-33e27c92a114"
        }
    ]
}

Create Users in Bulk

You can create multiple users with the Bulk API call (the number of users is limited to a maximum of 50 per call). We recommend you limit the number of bulk calls to 5 per sec (250 users/second).

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{
  "customers": [
    {
      "firstname": "Mike",
      "lastname": "Doel",
      "customer_id": "12345",
      "email": "test_api_user@getblueshift.com"
    },
    {
      "firstname": "John",
      "lastname": "Doel",
      "customer_id": "123456",
      "email": "test_api_user_2@getblueshift.com"
    }
  ]
}' -u <USER_API_KEY>:  https://api.getblueshift.com/api/v1/customers/bulk

Returns (on no errors):

JSON

{
  "customers": [
  ],
  "errors": [    
  ]
}

Sample return with errors:

JSON

{
  "customers": [
    {
      "firstname": "Mike",
      "lastname": "Doel",
      "email": "test_api_user@getblueshift.com",
      "gender": "k",
      "customer_id": "12345"
    },
    {
      "firstname": "Chuck",
      "lastname": "Norris",
      "email": "test_api_user2@getblueshift.com",
      "customer_id": "1234567"
    }
  ],
  "errors": [
    {
      "status": 400,
      "error_data": {
        "gender": [
          "is other than 'male', 'female', 'unknown'."
        ]
      }
    },
    {
      "status": 500,
      "error_data": {
        "message": "Interanl Server Error"
      }
    }
  ]
}

Forget User

You can use the forget me endpoint to permanently delete all personal data about the user. Once a user is forgotten, Blueshift will stop tracking the user and the user will be excluded from any campaign's from blueshift. You can use the forget me endpoint with email or customer_id.

It will take couple of hours for the data to be deleted once the user is forgotten.

This action is irreversible and all the user data will be permanently deleted

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"email":"test@gmail.com"}' -u <USER_API_KEY>:  https://api.getblueshift.com/api/v1/customers/forget

Unforget User

You can use the unforget endpoint to enable user tracking. The user will be eligible for any campaigns in the future. Unforget does not restore any old data for the user

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"email":"test@gmail.com"}' -u <USER_API_KEY>:  https://api.getblueshift.com/api/v1/customers/unforget

Delete User

You can use the delete endpoint to permanently delete all personal data about the user

It will take couple of hours for the data to be deleted once the user is deleted

This action is irreversible and all the user data will be permanently deleted

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"email":"test@gmail.com"}' -u <USER_API_KEY>:  https://api.getblueshift.com/api/v1/customers/delete

If there are multiple profile matches, /delete will only delete the first matching user. To delete all matching profiles set delete_all_matching_customers=true in the api call.

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"email":"test@gmail.com"}' -u <USER_API_KEY>:  https://api.getblueshift.com/api/v1/customers/delete?delete_all_matching_customers=true

Merge User

You may use the User Merge API end point to programmatically merge two user profiles, effectively unifying them as one. You may choose to use this end-point to:

Merge 2 users with different customer_ids
Update the customer_id of an existing customer in Blueshift

Attribute	Description
email or customer_id or both	Previous/current unique identifier for the user in Blueshift
bsft_new_customer_id	customer_id for the target user

The endpoint is throttled at 1.5K calls/min. Please reach out to support@blueshift.com if you want to increase the rate limits or if you have any questions.

cURL

curl  -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"customer_id":"K12330", "bsft_new_customer_id": "K12327"}' -u <USER_API_KEY>:  https://api.getblueshift.com/api/v1/customers/merge

Note:

If no users are present in blueshift with either a combination of email/customer_id or bsft_new_customer_id - we will create a new user with bsft_new_customer_id
If both users exist, the profile data of the old user will get merged to the new user (bsft_new_customer_id).
If there are multiple user profile matches, say if you provide an email and there are multiple users associated with that email, Blueshift will only update the most recent user profile, in such cases we recommend you to use the customer_id if you have multiple profiles on an email
If a user exists with an email/customer_id, but no user exists with bsft_new_customer_id - Blueshift will update the customer_id for the existing user to bsft_new_customer_id

Error Codes & Responses

Code	Text	Description
400	Bad Request	The request was invalid or cannot be otherwise served. An accompanying error message will explain further
404	Resource not found	Can happen due to resource conflict's, re-try with exponential backoff, if the issue is not resolved please contact blueshift
409	Conflict error, please retry	The request could not be completed due to a conflict with the current state of the target resource, re-try with exponential backoff
413	You can upload maximum 50 users in one api call	The server is refusing to process a request because the request payload is larger than the server is willing or able to process.
429	Rate limit exceeded	Too many requests, please contact blueshift for recommended throughput's.
500	Internal Server Error	Please contact Blueshift for more information
502	Service unavailable, please retry	Bad Gateway, re-try with exponential backoff
503	Service unavailable, please retry	Service Unavailable, re-try with exponential backoff
504	Service unavailable, please retry	Gateway Timeout, please re-try with exponential backoff