User Update
Request Details
Item | Value |
Description | Update an existing CrowdTwist user, you must perform an HTTP PUT request with a JSON object. |
Method | PUT |
Endpoint | https://[environment]api[client_id].crowdtwist.com/v2/users/[user_id]?api_key=[api_key]&id_type=[id_type] |
Content Type: | JSON (application/json) |
Request
Field Name | Sample Value | Required | Format | Notes |
URL PARAMETERS | ||||
user_id | alice@crowdtwist.com | Yes | String | Unique ID of the user for whom activities will be returned: Options: – Email Address – Facebook User ID – Twitter User ID – CrowdTwist ID – Third Party ID – Username – Mobile Phone Number |
QUERY STRING PARAMETERS | ||||
api_key | QWERTYUIOP | Yes | String | |
id_type | No | String | Type of ID being Sent: Options: – facebook_user_id – twitter_user_id – id (CrowdTwist ID) – default ID if id_type is not specified – third_party_id – username – mobile_phone_number |
REQUEST BODY: Standard CrowdTwist User Object | ||||
Field Name | Sample Value | Required | Format | Notes |
first_name | Mike | Yes | String | User’s first name. Allowed values: /^[-\’ \p{L}0-9- _@\.,]+$/u |
last_name | Smith | Yes | String | User’s last name. Allowed values: /^[-\’ \p{L}0-9- _@\.,]+$/u |
date_of_birth | 312724800 | No | Number | User’s date of birth in Epoch (UNIX) format Required & validated if COPPA is enabled. |
email_address | a@gmail.com | Yes | Email address currently associated with user in CrowdTwist platform. Allowed values are outlined here | |
email_is_verified | 1 | No | Boolean | Boolean indicating if user’s email address is verified Example values: 0, 1 (default: 1). |
is_active | 1 | No | Boolean | Boolean indicating if a user is active in CrowdTwist. Example values: 0, 1 (default: 1). |
remove_points | 1 | No | Boolean | Optional field to be sent with is_active that removes the member's points when the member is deactivated. |
lang_pref | en | No | String | String value indicating the language preference code for a member. If it is not provided for a member, this will return as null. Click here for a list of accepted language codes. |
postal_code | No | String | US Postal Code
There is validation logic that doesn’t allow city, country, etc when a postal_code is provided. This means that for domestic addresses ONLY postal_code can be provided. CrowdTwist also has the ability to accept 9-digit postal codes, with or without the hyphen (-) in a User Create or User Update request. We will only perform validation on the first 5 digits. |
|
username | mikesmith | No | String | CrowdTwist system ID associated with user |
password | abcdef | No | String | User password |
third_party_id | 103997 | No | String | Unique value within client’s systems |
city_id | 834694 | No | Number | Internal CrowdTwist city ID value. Lookup table provided on request by the CrowdTwist team. Attribute used for members outside of US & Canada. |
city_name | London | No | String | English city name |
country_code | US | Number | Internal CrowdTwist country ID value country_code should follow the ISO 3166-1 alpha 2 standard. Note, ISO 3166-1 alpha 2 standard isn’t a numeric value, it’s a 2 character alpha value read more. |
|
facebook_access_token | No | String | Facebook access token | |
facebook_user_id | 1226136555 | No | String | Facebook ID associated with the user in the CrowdTwist platform |
inst_access_token | Null | No | String | Instagram access token |
inst_username | Null | No | String | Instagram username |
inst_user_id | Null | No | String | Instagram user id |
fsq_access_token | No | String | FourSquare access token | |
fsq_user_id | No | String | Foursquare ID associated with user in CrowdTwist platform | |
extra_data | null | No | JSON | Extra data set via Control Center |
gender_id | 1 | No | Number | Internal CrowdTwist gender ID value. Use the ID values below to populate this field. 1 = Female 2 = Male 3 = Non-binary 4 = Other 5 = Prefer not to identify |
middle_name | No | String | User middle name | |
mobile_phone_number | 2127177932 | No | Number | User’s mobile phone number must be unique, 6-20 digits allowed. Any symbols, spaces, or letters within the phone number will be removed leaving the 6-20 digit string |
receive_email_updates | 1 | No | Boolean | Boolean indicating if should receive email updates Example values: 0, 1 (default: 1) updates from CrowdTwist platform |
custom_data | { “register_id” : “1”, “cashier_id” : “2” } |
No | Object | Client-defined attributes can be sent via the custom_data request object. Custom Data attributes for your program can be configured via Control Center. For a list of configured attributes, please work with your CrowdTwist representative. |
tier_override | { “level_id”:68, “timeframe_score”:200 } |
No | JSON Array | level_id: CrowdTwist defined Tier ID used to override a member’s tier level. Used on Tiers V2 only. Contact your CrowdTwist team for your program’s level ID’s timeframe_score (optional): This is an override of the cumulative score the member has earned in the current timeframe since the member last expired. |
password_generated | 1 | No | String | Indicates if password was generated by CrowdTwist |
Custom_Data Requirements
The custom_data field will contain a list of key-value data pairs that are specified by the client. Note: If there are key(s) that were not identified by the client to CrowdTwist, then the unknown key(s) will not be saved and will result in an error response.
- Attribute names can be up to 100 character long
- Attribute values can be up to 512 characters long
- Any attributes to be sent need to be known by CrowdTwist prior to integration.
For example:
- {“error”: “input_error”, “message”: “No custom attributes setup for client 12.”}
- {“error”: “input_error”, “message”: “Unrecognized attribute name bar for client 12.”}
Sample Request
curl -X PUT https://api.crowdtwist.com/v2/users/alice@crowdtwist.com?api_key=QWERTYUIOP&id_type=email { "email_address": "alice@crowdtwist.com", "last_name": "Twist", "first_name": "Alice", "lang_pref":null, "postal_code": "10010", "date_of_birth": 344754000, "username": "alicetwist", "email_is_verified": 1, "send_verify_email": 0, "sign_up_channel_id": 1, "custom_data": { "register_id": "1", "cashier_id": "2" } }
curl -X PUT https://api.crowdtwist.com/v2/users/alice@crowdtwist.com?api_key=QWERTYUIOP&id_type=email { "email_address": "alice@crowdtwist.com", "last_name": "Twist", "first_name": "Alice", "lang_pref":null, "postal_code": "10010", "date_of_birth": 344754000, "username": "alicetwist", "email_is_verified": 1, "send_verify_email": 0, "sign_up_channel_id": 1, "custom_data": { "register_id": "1", "cashier_id": "2" } }
Sample Successful Response
{ "id": 11601, "first_name": "Alice", "middle_name": null, "last_name": "Twist", "lang_pref":null, "date_of_birth": 344754000, "email_address": "alice@crowdtwist.com", "email_is_verified": true, "username": "alicetwist", "mobile_phone_number": null, "third_party_id": null, "is_active": true, "gender_id": null, "gender": null, "extra_data": null, "continent": "North America", "country": "United States", "us_region": "Northeast", "ca_province": null, "state": "NY", "city": "New York City", "street_address_1": null, "street_address_2": null, "postal_code": "10010", "receive_email_updates": true, "date_receive_email_opt_in": 1461706842, "date_receive_email_opt_out": null, "total_points": 2000, "redeemable_points": 2000, "num_points_purchased": 0, "facebook_access_token": null, "facebook_user_id": null, "date_fb_token_expires": null, "twitter_oauth_token": null, "twitter_oauth_token_secret": null, "google_access_token": null, "google_refresh_token": null, "google_user_id": null, "yahoo_access_token": null, "yahoo_access_token_secret": null, "yahoo_session_handle": null, "yahoo_user_id": null, "inst_access_token": "1021870.a470c0c.b4f7e07fb0224dc8a97d08466a087b4d", "inst_username": "crowdtwist_test", "inst_user_id": "1021870", "activity_stream_opt_in": true, "store_id": null, "date_last_login": null, "date_last_updated": 1461777590, "date_created": 1461706842, "rank": null, "weekly_rank": null, "monthly_rank": null, "salt": null, "hash_algorithm_id": "1", "lang_pref": "en", "referral_url": "", "fan_level": "Bronze", "sign_up_channel_id": 1, "custom_data": { "register_id": "1", "cashier_id": "2" }, "tier_info": { "current_level": { "title": "Bronze", "min_value": "2000", "max_value": "9999" }, "next_level": null, "levels_above": [], "levels_below": [], "date_assigned": null, "expiration_date": null, "reset_date": null, "score_needed_to_reach": null, "score_needed_to_maintain": null, "days_until_expiration_date": null, "days_until_reset_date": null, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "maintain", "timeframe_score": null, "tier_score": null, "segments": [], "password_generated": "0" } }
{ "id": 11601, "first_name": "Alice", "middle_name": null, "last_name": "Twist", "lang_pref":null, "date_of_birth": 344754000, "email_address": "alice@crowdtwist.com", "email_is_verified": true, "username": "alicetwist", "mobile_phone_number": null, "third_party_id": null, "is_active": true, "gender_id": null, "gender": null, "extra_data": null, "continent": "North America", "country": "United States", "us_region": "Northeast", "ca_province": null, "state": "NY", "city": "New York City", "street_address_1": null, "street_address_2": null, "postal_code": "10010", "receive_email_updates": true, "date_receive_email_opt_in": 1461706842, "date_receive_email_opt_out": null, "total_points": 2000, "redeemable_points": 2000, "num_points_purchased": 0, "facebook_access_token": null, "facebook_user_id": null, "date_fb_token_expires": null, "twitter_oauth_token": null, "twitter_oauth_token_secret": null, "google_access_token": null, "google_refresh_token": null, "google_user_id": null, "yahoo_access_token": null, "yahoo_access_token_secret": null, "yahoo_session_handle": null, "yahoo_user_id": null, "inst_access_token": "1021870.a470c0c.b4f7e07fb0224dc8a97d08466a087b4d", "inst_username": "crowdtwist_test", "inst_user_id": "1021870", "activity_stream_opt_in": true, "store_id": null, "date_last_login": null, "date_last_updated": 1461777590, "date_created": 1461706842, "rank": null, "weekly_rank": null, "monthly_rank": null, "salt": null, "hash_algorithm_id": "1", "lang_pref": "en", "referral_url": "", "fan_level": "Bronze", "sign_up_channel_id": 1, "custom_data": { "register_id": "1", "cashier_id": "2" }, "tier_info": { "current_level": { "title": "Bronze", "min_value": "2000", "max_value": "9999" }, "next_level": null, "levels_above": [], "levels_below": [], "date_assigned": null, "expiration_date": null, "reset_date": null, "score_needed_to_reach": null, "score_needed_to_maintain": null, "days_until_expiration_date": null, "days_until_reset_date": null, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "maintain", "timeframe_score": null, "tier_score": null, "segments": [], "password_generated": "0" } }
Sample Response – Tiers V1 Configuration
"tier_info": { "current_level": { "title": "Bronze", "min_value": "2000", "max_value": "9999" }, "next_level": null, "levels_above": [], "levels_below": [], "date_assigned": null, "expiration_date": null, "reset_date": null, "score_needed_to_reach": null, "score_needed_to_maintain": null, "days_until_expiration_date": null, "days_until_reset_date": null, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "maintain", "timeframe_score": null, "tier_score": null }
"tier_info": { "current_level": { "title": "Bronze", "min_value": "2000", "max_value": "9999" }, "next_level": null, "levels_above": [], "levels_below": [], "date_assigned": null, "expiration_date": null, "reset_date": null, "score_needed_to_reach": null, "score_needed_to_maintain": null, "days_until_expiration_date": null, "days_until_reset_date": null, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "maintain", "timeframe_score": null, "tier_score": null }
Sample Response – Tiers V2 Lifetime Configuration
"tier_info": { "current_level": { "title": "Silver", "min_value": 2500, "max_value": 4999 }, "next_level": { "title": "Gold", "min_value": 5000, "max_value": null }, "levels_above": [ { "title": "Gold", "min_value": 5000, "max_value": null } ], "levels_below": [ { "title": "Bronze", "min_value": null, "max_value": 2499 } ], "date_assigned": "2017-02-08T02:37:44Z", "expiration_date": null, "reset_date": null, "score_needed_to_reach": 2000, "score_needed_to_maintain": null, "days_until_expiration_date": 0, "days_until_reset_date": 0, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "jump", "timeframe_score": 3000, "tier_score": 3000 }
"tier_info": { "current_level": { "title": "Silver", "min_value": 2500, "max_value": 4999 }, "next_level": { "title": "Gold", "min_value": 5000, "max_value": null }, "levels_above": [ { "title": "Gold", "min_value": 5000, "max_value": null } ], "levels_below": [ { "title": "Bronze", "min_value": null, "max_value": 2499 } ], "date_assigned": "2017-02-08T02:37:44Z", "expiration_date": null, "reset_date": null, "score_needed_to_reach": 2000, "score_needed_to_maintain": null, "days_until_expiration_date": 0, "days_until_reset_date": 0, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "jump", "timeframe_score": 3000, "tier_score": 3000 }
Sample Response – Tiers V2 Fixed Timeframe Configuration
"tier_info": { "current_level": { "title": "Silver", "min_value": 4000, "max_value": 7999 }, "next_level": { "title": "Gold", "min_value": 8000, "max_value": null }, "levels_above": [ { "title": "Gold", "min_value": 8000, "max_value": null } ], "levels_below": [ { "title": "Bronze", "min_value": null, "max_value": 3999 } ], "date_assigned": "2017-02-08T21:13:03Z", "expiration_date": "2019-02-06T05:00:00Z", "reset_date": "2018-02-06T05:00:00Z", "score_needed_to_reach": 4000, "score_needed_to_maintain": 4000, "days_until_expiration_date": 727, "days_until_reset_date": 362, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "jump", "timeframe_score": 2000, "tier_score": 1000 }
"tier_info": { "current_level": { "title": "Silver", "min_value": 4000, "max_value": 7999 }, "next_level": { "title": "Gold", "min_value": 8000, "max_value": null }, "levels_above": [ { "title": "Gold", "min_value": 8000, "max_value": null } ], "levels_below": [ { "title": "Bronze", "min_value": null, "max_value": 3999 } ], "date_assigned": "2017-02-08T21:13:03Z", "expiration_date": "2019-02-06T05:00:00Z", "reset_date": "2018-02-06T05:00:00Z", "score_needed_to_reach": 4000, "score_needed_to_maintain": 4000, "days_until_expiration_date": 727, "days_until_reset_date": 362, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "jump", "timeframe_score": 2000, "tier_score": 1000 }
Sample Response – Tiers V2 Rolling Timeframe Configuration
"tier_info": { "current_level": { "title": "Silver", "min_value": 4000, "max_value": 7999 }, "next_level": { "title": "Gold", "min_value": 8000, "max_value": null }, "levels_above": [ { "title": "Gold", "min_value": 8000, "max_value": null } ], "levels_below": [ { "title": "Bronze", "min_value": null, "max_value": 3999 } ], "date_assigned": "2017-02-08T21:19:07Z", "expiration_date": "2018-02-08T21:19:07Z", "reset_date": null, "score_needed_to_reach": 4000, "score_needed_to_maintain": 4000, "days_until_expiration_date": 365, "days_until_reset_date": 0, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "jump", "timeframe_score": 2000, "tier_score": 1000 }
"tier_info": { "current_level": { "title": "Silver", "min_value": 4000, "max_value": 7999 }, "next_level": { "title": "Gold", "min_value": 8000, "max_value": null }, "levels_above": [ { "title": "Gold", "min_value": 8000, "max_value": null } ], "levels_below": [ { "title": "Bronze", "min_value": null, "max_value": 3999 } ], "date_assigned": "2017-02-08T21:19:07Z", "expiration_date": "2018-02-08T21:19:07Z", "reset_date": null, "score_needed_to_reach": 4000, "score_needed_to_maintain": 4000, "days_until_expiration_date": 365, "days_until_reset_date": 0, "is_maintenance_mode": true, "date_reached": "2017-03-23T19:00:00Z", "assigned_by_event": "jump", "timeframe_score": 2000, "tier_score": 1000 }
Sample Error Response: Status Code 400 – COPPA Non-compliant Birthdate
{ "error":"input_error", "message":"User does not meet the age requirements for this program" }
{ "error":"input_error", "message":"User does not meet the age requirements for this program" }
Sample Error Response: Status Code 400 – Incorrect Postal Code
{ "error":"input_error", "message":"US zip code or country/city combo is required" }
{ "error":"input_error", "message":"US zip code or country/city combo is required" }
Sample Error Response: Status Code 400 – 2 Requests Made In Rapid Succession
{ "error":"input_error", "message":"Event already processed" }
{ "error":"input_error", "message":"Event already processed" }
Error Response Codes
Error | Message | Message |
input_error | Returned whenever the request is missing required fields, including situations in which the body is malformed (e.g. HTTP method not supported, receipt not found, etc.). | Sample Messages: “Invalid data sent.” “first_name is invalid” “last_name is invalid” “email_address already taken” “No custom attributes setup for client 12.” “Unrecognized attribute name bar for client 12.” “Password did not meet the Security requirements.” |
internal_error | HTTP error status code is returned due to an error that occurred in the backend. | internal_error: unexpected error occurred in the CrowdTwist backend |