User Profile


Request Details

Item Value
Description Returns user profile for a given member.
Method GET
Endpoint https://api.crowdtwist.com/v2/users/[user_id]/?api_key=[api_key]&id_type=[id_type]


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


Successful Response

Field Name Sample Value Required Format Description
id 16 Yes String Internal CrowdTwist member user_id
first_name Alice Yes Integer User’s first name
middle_name null Yes Integer User’s middle name
last_name Twist Yes Integer User’s last name
date_of_birth null User DOB
email_address alice@crowdtwist.com Yes String User email
email_is_verified true Yes Integer User email is verified
username Alice Yes String User username
mobile_phone_number null No Integer User phone number
third_party_id null Yes String User Third party ID
is_active true Yes User is active
gender_id null Yes Gender ID
gender null Yes Gender mentioned
extra_data null No Extra data provided
continent North America Yes String Continent provided
country United States Yes String Country provided
us_region Northeast No String US region provided
ca_province null No String CA province provided
state NY Yes String State provided
city New York City Yes String City provided
street_address_1 null No String Street-1
street_address_2 null No String Street-2
postal_code 10001 Yes Integer Postal code provided
receive_email_updates false No String Email Updates
date_receive_email_opt_in null No String Date of receive email IN
date_receive_email_opt_out null No String Date of
receive email OUT
total_points 1000 Integer Total points of the user
redeemable_points 1000 Integer Redeemable points of the user
num_points_purchased 0 No Integer Num points purchased
facebook_access_token Null No Facebook access token
facebook_user_id Null No Facebook user Id
date_fb_token_expires Null No FB token expires
twitter_oauth_token Null No Twitter oauth token
twitter_oauth_token_secret Null No Twitter oauth token secret
google_access_token Null No Google access token
google_refresh_token Null No Google refresh token
google_user_id Null No Google user ID
yahoo_access_token Null No Yahoo access token
yahoo_access_token_secret Null No Yahoo access token secret
yahoo_session_handle Null No Yahoo session handle
yahoo_user_id Null No Yahoo session ID for the user
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
activity_stream_opt_in Null No Activity streem
store_id Null No Store ID
date_last_login 1460787298 No Last date login
date_last_updated 1460787301 No Last date updated
date_created 1460787285 No Created date
rank Null No Rank of the user
weekly_rank Null No Weekly rank of the user
monthly_rank Null No Monthly rank of the user
salt Null No Salt
hash_algorithm_id 1 No Hash algorithm ID for the user
lang_pref en No Language preference of the user
referral_url http://program.crowdtwist.com?_cts_=gD2S1W8P No Referral URL
fan_level New Fan Yes Fan level of the User
sign_up_channel_id 1 No Channel id of user sign-up
custom_data {
“register_id” : “1”,
“cashier_id” : “2”}
}
No Custom Data JSON object (parameters are configurable by client)
tier_info     object<tier_info> Object containing all tiers data
level data     object<level_data> Object containing title, min_value, max_value of a tier
– title Silver   String Name of a tier
– min_value 4000   String Number of points required to attain or maintain a tier
– max_value 7999   String Number of points configured as the upper limit of a tier
current_level {“title”: “Silver”, “min_value”:4000, “max_value”:7999}   object<level_data> Level data of a user’s current tier
next_level {“title”: “Gold”, “min_value”:8000, “max_value”:9999}   object<level_data> Level data of a user’s next tier
levels_above [{“title”: “Gold”, “min_value”:8000, “max_value”:9999}, {“title”: “Platinum”, “min_value”:10000, “max_value”:null}]   Array[level_data] Array containing level data on all levels above a user’s current tier. (Will be null if user is in highest tier).
levels_below [{“title”: “Bronze”, “min_value”:null, “max_value”:3999}]   Array[level_data] Array containing level data of all levels below a user’s current tier. (Will be null if user is in lowest tier).
date_assigned 2017-02-08T02:37:44Z   String (ISO 8601 Format) Date the member reached their current tier
date_reached 2017-03-23T19:00:00Z   String Date the member reached their current tier. This only changes when a member drops or jumps a tier.
assigned_by_event jump   String The event that occurred when a member is assigned a tier (i.e. start, jump, maintain, drop, reset)
Is_maintenance_mode true   Boolean Boolean indicating whether the user’s points will count towards maintaining current level.
expiration_date 2019-02-06T05:00:00Z   String (ISO 8601 Format) Date the member’s tier will expire (for both fixed and rolling)
reset_date 2018-02-06T05:00:00Z   String (ISO 8601 Format) Date the member resets to 0 and enters maintenance (only for fixed timeframe, otherwise null)
score_needed_to_reach 4000   Numeric Number of points needed for a member to advance to next tier
score_needed_to_maintain 4000   Numeric Number of points needed for a member to maintain current tier
days_until_expiration_date 727   Numeric Number of days until a member’s tier expires if they do not maintain
days_until_reset_date 362   Numeric Number of days until a member’s tier resets (only for fixed timeframe, otherwise null)
timeframe_score 1500   Numeric 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. 
tier_score 250   Numeric The points earned while the member is in a tier


Error Response

Field Name Sample Value Required Format Description
error param_error Yes String A machine readable code that describes the error.
message User does not exist Yes String A short, descriptive sentence detailing the error.


Error Response Codes

Error Message
input_error The input provided in invalid or formatted incorrectly.
internal_error Something went wrong on our end.
page_not_found The requested page does not exist or has been removed.


Sample Request

curl -X GET
'https://api.crowdtwist.com/v2/users/alice@crowdtwist.com/?api_key=QWERTYUIOP&id_type=email'
curl -X GET
'https://api.crowdtwist.com/v2/users/alice@crowdtwist.com/?api_key=QWERTYUIOP&id_type=email'


Sample Successful Response: Status Code 200

{
  "id": 11601,
  "first_name": "Alice",
  "middle_name": null,
  "last_name": "Twist",
  "date_of_birth": null,
  "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": "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
  }
{
  "id": 11601,
  "first_name": "Alice",
  "middle_name": null,
  "last_name": "Twist",
  "date_of_birth": null,
  "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": "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 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

{
   "error": "page_not_found",
   "message": "user does not exist."
}
{
   "error": "page_not_found",
   "message": "user does not exist."
}