User Create


Request Details

Item Value
Description To create a user via the CrowdTwist API, you must perform an HTTP POST request with a JSON object.
Method POST
Endpoint https://api.crowdtwist.com/v2/users?api_key=[api_key]
Content Type: JSON (application/json)


Request

Field Name Sample Value Required Format Notes
URL PARAMETERSnone
QUERY STRING PARAMETERS
api_key QWERTYUIOP Yes String


REQUEST BODY: Standard CrowdTwist User Object

Field Name Sample Value Required Format Notes
first_name Mike Yes String User’s first name
last_name Smith Yes String User’s last name
date_of_birth No Number User’s date of birth
*required if COPPA is enabled.
email_address a@gmail.com Yes Email Email address currently associated with user in CrowdTwist platform
email_is_verified 1 Yes Boolean Boolean indicating if user’s email address is verified Example values: 0, 1 (default: 1).
postal_code Yes 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.
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 for US & CA, Yes for other countries Number Internal CrowdTwist city ID value. Lookup table provided on request by the CrowdTwist team.
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
gender_id 1 No  Number Internal CrowdTwist gender ID value. Use the ID values below to populate this field.
1 = Female
2 = Male
0 = Null
middle_name No String User middle name
mobile_phone_number 2127177932 No Number Users mobile phone number must be unique.
receive_email_updates 1 No Boolean Boolean indicating if should receive email updates Example values: 0, 1 (default: 1) updates from CrowdTwist platform
send_verify_email 1 Yes Boolean Flag denoting if email verification email should be sent at time of user creation Example value: 0, 1 (default: 1)
sign_up_campaign SpringMediaBuy No String ID to associate user registration with for reporting / analytics purposes
sign_up_channel_id 1 No Number Value to indicate where user registration occurred.
1 = In Store
2 = Online
3 = Kiosk / In Store Other
4 = Call Center
5 = Mobile App
6 = Other
7 = Receipt Scan
8 = Affiliate
9 = Outlet
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.
Attribute Names:
employee_id
cashier_id
register_id
store_loc
plcc
cardholder_status
tier – used for client defined tiers on Tiers V1 only. Tier ID value to be provided by CrowdTwist.
user_operation – used to determine whether api call was user create or user update
subscriber_type
tier_override 1 No String CrowdTwist defined Tier ID used to override a member’s tier level. Used on Tiers V2 only.


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 POST
https://api.crowdtwist.com/v2/users?api_key=QWERTYUIOP
{
  "email_address": "alice@crowdtwist.com",
  "last_name": "Twist",
  "first_name": "Alice",
  "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 POST
https://api.crowdtwist.com/v2/users?api_key=QWERTYUIOP
{
  "email_address": "alice@crowdtwist.com",
  "last_name": "Twist",
  "first_name": "Alice",
  "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",
  "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": "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
  }
}
{
  "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": "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 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
  }

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.”
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
Internal error trying to register user to third party