CrowdTwist

Sync member profiles and award activity points in Oracle CrowdTwist loyalty programs. Zeotap connects to the CrowdTwist REST API v2 to create and update loyalty members, and to credit activities with points.

Prerequisites

• An Oracle CrowdTwist account with API access enabled
• Your CrowdTwist API base URL (e.g. https://api123.crowdtwist.com)
• An API key or HMAC key pair from your CrowdTwist Control Center
• Activity IDs configured in CrowdTwist (if syncing activity credits)

Permissions

Your API key must have permissions to:

• Create and update user profiles (POST /v2/users, PUT /v2/users/{id})
• Credit activities (POST /v2/users/{id}/activities) — if using the Activity Credit object type
• List activities (GET /v2/activities) — used for connection testing

Authentication

CrowdTwist supports two authentication methods:

API Key Authentication

1. In CrowdTwist Control Center, navigate to Settings > API
2. Locate or generate your API Key
3. Copy the API key value
4. In Zeotap, select API Key as the authentication method
5. Paste the key into the API Key field

HMAC Authentication

HMAC provides stronger security by signing each request with a shared secret.

1. In CrowdTwist Control Center, navigate to Settings > API
2. Locate your Public Key (key identifier) and Private Key (key secret)
3. In Zeotap, select HMAC Authentication as the authentication method
4. Paste the public key into the Public Key (Key Identifier) field
5. Paste the private key into the Private Key (Key Secret) field

HMAC authentication uses HMAC-SHA256 to sign each request. The signature includes the HTTP method, content MD5 hash, content type, timestamp, and request URI. Timestamps must be within 15 minutes of the server time.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

CrowdTwist does not have a list or segment membership API, so audience sync modes are not supported.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

User Profile

user_id, email_address, first_name, last_name, postal_code, date_of_birth, gender_id, mobile_phone_number, third_party_id, lang_pref, country_code, city_name, receive_email_updates

Activity Credit

user_id, activity_id, num_points, activity_date

How It Works

User Profile Sync

1. For each row in the batch, Zeotap extracts the user identifier from the user_id mapped field
2. Known CrowdTwist fields (e.g. email_address, first_name, postal_code) are mapped directly to the API payload
3. Any unmapped fields are placed in the custom_data object (custom attributes must be pre-configured in CrowdTwist Control Center)
4. In upsert mode, Zeotap first attempts a PUT to update the user; if the user is not found, it falls back to a POST to create the user
5. In insert mode, only POST requests are sent to create new users
6. In update mode, only PUT requests are sent to update existing users

Activity Credit Sync

1. For each row, Zeotap extracts the user_id and activity_id fields
2. A POST request is sent to /v2/users/{user_id}/activities with the activity payload
3. Optional fields num_points (to override default point value) and activity_date (for backdating) are included if mapped

Request Processing

CrowdTwist does not offer a bulk API — each user is processed individually. Zeotap handles this by:

• Sending one API request per row
• Automatically retrying on transient errors (HTTP 429, 5xx) with exponential backoff
• Respecting Retry-After headers when rate-limited
• Logging per-row errors for troubleshooting

Rate Limits

CrowdTwist enforces rate limits at the instance level. Specific limits vary by account and are configured by Oracle. Zeotap automatically handles rate limiting by:

• Retrying requests that receive HTTP 429 responses
• Using exponential backoff with a maximum of 3 retries
• Respecting Retry-After headers

Duplicate requests sent in rapid succession may return an "Event already processed" error — this is normal and indicates the previous request was accepted.

Best Practices

• Choose the right identifier type: Use email for consumer programs or third_party_id for enterprise integrations where you manage your own user IDs
• Pre-configure custom attributes: Any custom fields you plan to sync must be set up in CrowdTwist Control Center before syncing, or the API will reject them
• Use upsert mode for most use cases — it handles both new and existing members gracefully
• Validate postal codes: US postal codes must be 5 digits; Canadian postal codes must follow the L#L #L# format. International addresses require country_code and either city_id or city_name
• Test with a small batch first: Since CrowdTwist processes users individually, start with a small sync to verify field mappings before running large syncs

Troubleshooting

Authentication failed: invalid credentials

Verify your API key or HMAC key pair in CrowdTwist Control Center under Settings > API. For HMAC auth, ensure both the public key (key identifier) and private key (key secret) are correct. HMAC timestamps must be within 15 minutes of the server time — check that your system clock is synchronized.

”email_address already taken” error

This error occurs when creating a user with an email that already exists. Switch to upsert or update sync mode to update existing users instead of creating duplicates.

”No custom attributes setup for client” error

Custom data fields must be pre-configured in CrowdTwist Control Center before they can be used via the API. Navigate to your program settings and add the custom attribute, then retry the sync.

”Unrecognized attribute name” error

The field name in your mapping does not match a configured custom attribute in CrowdTwist. Check the exact attribute name in Control Center — attribute names are case-sensitive and must match exactly.

”US zip code or country/city combo is required” error

CrowdTwist requires location information for user profiles. For US users, provide a 5-digit postal_code. For international users, provide country_code along with either city_id or city_name.

User not found during update

When using update mode, ensure the user_id value matches an existing user and that the User Identifier Type in the configuration matches the type of ID you are sending. For example, if you are sending email addresses, select “Email Address” as the identifier type.

Activity credit not awarding points

Activities may not award points due to frequency capping limits configured in CrowdTwist. Check your activity configuration in Control Center. Also verify that the activity_id is correct — the API returns a generic error if the activity ID does not exist.

Slow sync performance

CrowdTwist does not support bulk APIs, so each user is processed individually. For large syncs, expect longer processing times. Consider scheduling syncs during off-peak hours and breaking very large syncs into smaller batches.