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
| Attribute | |
| 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 |
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.
- 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/customersReturns
- JSON
{
"customer": {
"email": "test_api_user@getblueshift.com",
"firstname": "Mike",
"gender": "male",
"lastname": "Doel",
"customer_id": "1234",
"uuid": "06743da2-9589-4c01-afda-e3d85e487fa7"
}
}- 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-e3d85e487fa7Returns:
- 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"
}
}- 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.comReturns:
- 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/bulkReturns (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/forgetUnforget 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/unforgetDelete 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/deleteIf 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/mergeNote:
- 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 |