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://[environment]api[client_id].crowdtwist.com/v2/users?api_key=[api_key]
Content Type: JSON (application/json)


Request

Field Name Sample Value Required Format Notes
URL PARAMETERS – none
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.
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
invite_code A123XYZ No String The invite code for a member that was referred by a friend. If no invite is completed, this field does not need to be sent.

Invite code is pulled from the referral URL generated by CrowdTwist (_cts_=[code]). Please contact your CrowdTwist account team for more information.
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.
email_is_verified 1 No Boolean Boolean indicating if user’s email address is verified Example values: 0, 1 (default: 1).
postal_code 10010 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.

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.

street_address_1 110 E 23rd St No String First line of a street address
street_address_2 Apartment 405 No String Second line of a street address
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. For members outside of US & Canada, request a lookup table from CrowdTwist team to find specific city ID.
city_name London No String English city name
country_code US String 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
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
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

Additional Channel IDs can be configured in Control Center.
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
}		 No JSON Array 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
segments [
{
“name”: “Active Segment”,
“date_entered”: “2017-06-15T15:51:46.000Z”
},
{
“name”: “New Segment”,
“date_entered”: “2017-06-15T14:42:48.000Z”
}
]		 No Array List of segments associated with the user in CrowdTwist platform. If segmentation is not enabled for a client instance the array will be empty.
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 POST
https://api.crowdtwist.com/v2/users?api_key=QWERTYUIOP
{
  "email_address": "alice@crowdtwist.com",
  "last_name": "Twist",
  "first_name": "Alice",
  "postal_code": "10010",
  "lang_pref":"en",
  "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",
  "lang_pref":"en",
  "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":"en",
  "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",
  "referral_url": "",
  "fan_level": "Bronze",
  "sign_up_channel_id": 1,
  "custom_data": {
    "register_id": "1",
    "cashier_id": "2"
  }, 
 "segments": [], 
 "password_generated": "0",
 "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",
  "lang_pref":"en",
  "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",
  "referral_url": "",
  "fan_level": "Bronze",
  "sign_up_channel_id": 1,
  "custom_data": {
    "register_id": "1",
    "cashier_id": "2"
  }, 
 "segments": [], 
 "password_generated": "0",
 "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
  }

Sample Error Response: Status Code 400 – Input Errors 

{
   "error":"input_error",
   "message":"email_address parameter must be an email address"
}
{
   "error":"input_error",
   "message":"email_address parameter must be an email address"
}


{
   "error":"input_error",
   "message":"first_name is required"
}
{
   "error":"input_error",
   "message":"first_name is required"
}


{
   "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"
}


{
   "error":"input_error",
   "message":"first_name parameter must be a string"
}
{
   "error":"input_error",
   "message":"first_name parameter must be a string"
}


{
   "error":"input_error",
   "message":"mobile_phone_number already taken"
}
{
   "error":"input_error",
   "message":"mobile_phone_number already taken"
}


{
   "error":"input_error",
   "message":"email_address already taken"
}
{
   "error":"input_error",
   "message":"email_address already taken"
}


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 Description Message
invalid_auth Incorrect API key was used
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.”
“This program does not support the selected country.”
“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
Internal error trying to register user to third party