Submit a request
  1. Blueshift Documentation Hub
  2. Developer Docs
  3. API

User API

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

    1. User Attributes
    2. Create/Update User
    3. Get User
    4. Find User
    5. Bulk User Create
    6. Forget User
    7. Unforget User
    8. Delete User
    9. Merge User
    10. 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": "Internal 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  -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  -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  -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  -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  -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
 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request