Client Defined Segments

CrowdTwist lets you create custom segments using a predefined list of members through an upload process. This process utilizes a client-specific directory on the CrowdTwist SFTP. For tailored guidance on relevant use cases for your program, contact your dedicated support team.

Documentation and File Formatting Requirements

CrowdTwist requires the member file to meet the following criteria:

  • Member Identifiers: The file must include at least one column with a supported member identifier. Supported column headers (case-insensitive) are:

    • id (CrowdTwist ID - recommended)

      NOTE: The legacy header for Crowdtwist ID, CTUserID, is still supported for backwards compatibility.

    • third_party_id

    • email_address

    • username

    • mobile_phone_number

  • Priority Order: If multiple identifier columns are present, the system evaluates them in the order listed above. It stops after the first successful or failed match. If the highest-priority identifier doesn’t match a member in your program, the system moves to the next row.

  • Additional Columns: Any columns beyond the supported identifiers are ignored.

  • File Format: Save the file as a CSV file with UTF-8 encoding and without field enclosures (for example, quotation marks around values).

File Naming Convention

Files must follow this format:

[CUSTOM_SEGMENT_NAME]_YYYYMMDD_[SEGMENT_VERSION].csv

Example: SPECIAL_PROMOTION_20250915_0001.csv

Notes on Naming Convention:

  • Segment Version: [SEGMENT_VERSION] indicates the iteration of the segment. While starting with 0001 for the first version is recommended, it’s not required as long as subsequent versions on the same day have a higher number (for example, first version 1205, second version 1643).
  • Version Format: [SEGMENT_VERSION] must always be a 4-digit number.
  • Updates on Same Date: To update a previously processed segment on the same date, increment the [SEGMENT_VERSION] (for example, 0002, 0003) and re-upload to the SFTP.

  • Updates on Different Date: If updating on a different date, update the YYYYMMDD to the new upload date. The [SEGMENT_VERSION] can reset to 0001 (or any number, as long as subsequent versions on that date are higher).

  • Segment Name: [CUSTOM_SEGMENT_NAME] must use underscores (`_`) in place of spaces. These display as spaces in the Control Center (for example, SPECIAL_PROMOTION appears as SPECIAL PROMOTION).

  • Replacing vs. Appending Members: Subsequent uploads for the same segment will replace the existing member list. To append new members, include the full cumulative list (existing plus new members) in the updated file. Members omitted from the new file will be removed from the segment.

File Validations Rules: 

  • Maximum File Size: 128 MB

  • Duplicate Entries: Automatically removed during processing.

  • Invalid Data: Files with non-numeric entries in the id column are not processed and are marked as failed.

File Content Examples: 

  • Example 1: Using id

    id
54602377
54600375
54600597
54602359
58249083
54615470
58813384

  • Example 2: Using third_party_id

    third_party_id
14356297655
14359572597
14360688258
14360688664
14357664150
14355939701
14355540683

  • Example 3: Using email_address

    email_address
admin@example.com
test@example.com
member@example.com
user@example.com
contact@example.com

  • Example 4: Using mobile_phone_number

    mobile_phone_number
8905671234
5671234890
4891235670
5670123489
1238905467

Uploading Segments to SFTP: 

Upload segment files to the segment folder within your CrowdTwist SFTP directory. For assistance with accessing the SFTP, refer to the following resources: