Batch User Create

The CrowdTwist platform can consume user create and user update data via a JSON formatted batch file. The transaction data must be contained in a single file to ensure order of processing. Data is processed in the order present in the file. Files are processed in the order of the counter number in the file name. Details on the Batch User Update file format can be found here.

File naming convention:
Files must meet the following convention to be processed:

YYYYMMDD_<counter>_<client_id>_users_<client_specific>.json

Where:

YYYYMMDD represents the timestamp of the file with year, month, and day values according to the UTC time zone on the day the file is uploaded. If files are received with different dates, we cannot ensure they will be processed in date order. If files must be processed in order, the files must use the same date and the counter (see below).
<counter> represents an incrementing value of 4 digits beginning with 0001 (i.e. 0001, 0002, 0152…). This counter value will be used to indicate the order of files to be processed for a given day. Multiple files with the same date and counters greater than 1 will be processed in counter order. If a file with counter 0002 is received, the file will not be processed until 0001 is uploaded.
<client_id> represents a CrowdTwist generated client_id that will be provided at time of integration
<client_specific> represents any client-defined value

Example File Name:
20170623_0026_12_users_ClientUsers.json

File specifications:

Files must be sent via SFTP as a .json file type
Transactions must be sent, and will be processed, in the order present in the file.
- (i.e. a user update should not appear above a user create for a given user)
File size must not exceed 50 MB
Files must follow the naming convention outlined above
Files must be properly formatted JSON
All entries must be UTF-8

File Error Handling

The system will validate on the day and counter values for a given filename. If a file is received that contains an improper filename (incorrect day or value), processing will stop until a correctly formatted file is uploaded. For example, if a file is received with a counter value of 0003 before 0002 and 0001 are received, the file will not be processed until the previous files are received.

Transaction Error Handling:
A file may fail for any of the below example reasons:

A required field is missing
A field contains an invalid data type
A unique field has been duplicated
A corresponding user does not exist for a given user update

If transactions are sent in error, the system will log the errors in a downloadable file containing the failed JSON requests and continue processing the remaining transactions.

This error log will contain details on all failed requests. To reprocess any failed transaction, the client may resend the failed transactions in a new file.

Input Parameters:

User Data Object:
This object represents the entirety of the user creates and updates contained in the file. It is structured as an array of User Objects.

NOTE: There should only be a single instance of User Data per batch file and the object must be the first JSON element in the batch file.

User Data Object

Field Name	Sample Value	Notes	Required	Value Data Type
user_data		One batch per file provided	Yes	Array<user>

User Object:
This object defines the type of transaction being processed, i.e. create or update, and its associated data.

User Object
Field Name	Sample Value	Notes	Required	Value Data Type
type	create	String defining the type of transaction. In this case, the values can only be Create and Update	Yes	String
data		The detailed information for a single create or update	Yes	Create or Update
user_id	{ "email_address":"test@crowdtwist.com"<br> } { "email_address":"test@crowdtwist.com"<br> }	Gives client the ability to identify which user profile to update. The allowable user-identifying values are: id (internal CrowdTwist ID) email_address username third_party_id facebook_user_id twitter_user_id mobile_phone_number These user attributes are searched for in priority order. The system first checks id, then email, then username…etc., stopping once a match is found	Yes, only when type=update	UserId (see sample)

Create Object:
This object represents an entire profile to create a member, and includes all data related to a member. See the User Create API page for standard CrowdTwist user create requirements and the required Custom Data requirements.

Example:

{
  "user_data": [
    {
      "type": "create",
      "data": {
        "first_name": "Fred",
        "last_name": "Smith",
        "date_of_birth": 344772000,
        "email_address": "api@crowdtwist.com",
        "email_is_verified": 1,
        "postal_code": "10010",
        "username": "fredsmith",
        "password": "abc345",
        "third_party_id": "ABC123",
        "city_id": 4567,
        "country_code": "US",
        "facebook_access_token": null,
        "facebook_user_id": null,
        "fsq_access_token": null,
        "fsq_user_id": null,
        "gender_id": 1,
        "middle_name": null,
        "mobile_carrier_id": 4,
        "mobile_phone_number": 6468453654,
        "receive_email_updates": 1,
        "send_verify_email": 1,
        "sign_up_campaign": "SpringMediaBuy",
        "sign_up_channel_id": 1,
        "tier": "some_value_here",
        "twitter_oauth_token": null,
        "twitter_oauth_token_secret": null,
        "twitter_user_id": null,
        "subscriber_type": null,
        "custom_data": {
                "loyalty_join_date": "2018-11-04",
                "store_loc": null,
                "user_operation": "1",
                "employee_id": null,
                "cashier_id": null,
                "register_id": null,
                "store_id": 1234,
                "plcc": "true",
                "cardholder_status": "some_value_here",
                "user_operation": "some_value_here"
        }
      }
    }
  ]
}

{
  "user_data": [
    {
      "type": "create",
      "data": {
        "first_name": "Fred",
        "last_name": "Smith",
        "date_of_birth": 344772000,
        "email_address": "api@crowdtwist.com",
        "email_is_verified": 1,
        "postal_code": "10010",
        "username": "fredsmith",
        "password": "abc345",
        "third_party_id": "ABC123",
        "city_id": 4567,
        "country_code": "US",
        "facebook_access_token": null,
        "facebook_user_id": null,
        "fsq_access_token": null,
        "fsq_user_id": null,
        "gender_id": 1,
        "middle_name": null,
        "mobile_carrier_id": 4,
        "mobile_phone_number": 6468453654,
        "receive_email_updates": 1,
        "send_verify_email": 1,
        "sign_up_campaign": "SpringMediaBuy",
        "sign_up_channel_id": 1,
        "tier": "some_value_here",
        "twitter_oauth_token": null,
        "twitter_oauth_token_secret": null,
        "twitter_user_id": null,
        "subscriber_type": null,
        "custom_data": {
                "loyalty_join_date": "2018-11-04",
                "store_loc": null,
                "user_operation": "1",
                "employee_id": null,
                "cashier_id": null,
                "register_id": null,
                "store_id": 1234,
                "plcc": "true",
                "cardholder_status": "some_value_here",
                "user_operation": "some_value_here"
        }
      }
    }
  ]
}