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 email No String Type of ID being Sent:
Options:
– email
– 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 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.
Canadian Postal Code
A valid postal code must be provided if a value of “CA” is received in the country_code parameter. This must be formatted with a space and follow the “LXL XLX” format (L is a alphabetic character and X is a number). If a city_id is also provided it will not be validated.
Outside of the US or Canada
For countries outside of the US & Canada, city_id is used for location validation. The city_id and country_code combination are required for countries other than US & Canada.

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
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. The “custom_data” section sent in the User Update request body must contain the entire set of custom attributes for the user.

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.
Lifetime points: – Value is the same as “lifetime_points”.
Fixed timeframe: – Value is calculated from start date to start date – i.e. for an annual timeframe it calculates the total points earned between 1/1/16-12/31/16. This score will reset to 0 at the end of the reset date.
Rolling timeframe: -Value is calculated from when the user last expired i.e. if joined on 2/2/16 and jumped on 3/2/16 to gold, the timeframe score will be calculated until 3/2/17.

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