Talon.One

Loyalty and promotion engine for creating and managing personalized incentive campaigns. Sync customer profiles and audience memberships from your warehouse to Talon.One via their Integration API.

Prerequisites

• A Talon.One account with an active deployment
• An Integration API key generated in the Talon.One Campaign Manager
• Your deployment URL (e.g. https://yourcompany.talon.one)
• For audience syncs: the numeric Audience ID of the target audience in Talon.One

Permissions

The Integration API key must have access to the following endpoints:

• PUT /v2/customer_profiles — for customer profile syncs
• POST /v2/customer_audiences — for audience membership syncs

Authentication

Talon.One uses API Key authentication with the Integration API.

1. Log in to the Talon.One Campaign Manager
2. Navigate to Settings > Developer (or Settings > Integration API Keys)
3. Click Create API Key and give it a descriptive name
4. Copy the generated API key
5. In Zeotap, select API Key as the authentication method
6. Paste the API key into the Integration API Key field

The API key is sent as Authorization: ApiKey-v1 <your-key> on every request.

Configuration

Target Settings

Supported Operations

Sync Modes

Customer profiles are always upserted: new profiles are created and existing profiles are updated based on the Integration ID.

Audience Sync Modes

Audience sync modes require the Object Type to be set to Customer Profile Audiences. In Mirror mode, rows that leave the source query are automatically removed from the audience.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Customer Profiles

integration_id, email, name, phone, signup_date

Any additional mapped fields are sent as custom profile attributes. Custom attributes must be defined in Talon.One before syncing — they are not created automatically.

Customer Profile Audiences

Only the integration_id field is used. The Audience ID is configured in Target Settings.

How It Works

Customer Profile Syncs

1. Zeotap reads rows from your model or audience query
2. Rows are transformed according to your field mappings
3. Each row is mapped to a Talon.One customer profile with integrationId and custom attributes
4. Records are batched into groups of up to 1,000 per API call
5. Each batch is sent to PUT /v2/customer_profiles
6. New profiles are created automatically; existing profiles are updated
7. Zeotap retries transient failures (HTTP 429, 5xx) with exponential backoff

Audience Membership Syncs

1. Zeotap reads rows from your audience query
2. Each row is mapped to an audience membership action (add or delete)
3. In Add mode, all rows are sent as add actions
4. In Remove mode, all rows are sent as delete actions
5. In Mirror mode, new/changed rows are sent as add and removed rows as delete
6. Actions are batched into groups of up to 1,000 per API call
7. Each batch is sent to POST /v2/customer_audiences

API Payload Examples

Customer Profile upsert:

{
  "customerProfiles": [
    {
      "integrationId": "cust_12345",
      "attributes": {
        "email": "user@example.com",
        "name": "Jane Doe",
        "phone": "+1234567890"
      }
    }
  ]
}

Audience membership action:

{
  "data": [
    {
      "action": "add",
      "profileIntegrationId": "cust_12345",
      "audienceId": 42
    }
  ]
}

Rate Limits

• Batch size: Up to 1,000 customer profiles or audience actions per API call
• Rate limit: Varies by plan; typically 60 requests per second per deployment
• Maximum throughput: Up to 5,000 messages per minute (contact Talon.One for higher limits)

Zeotap automatically handles rate limiting with retry and exponential backoff.

Best Practices

• Use stable Integration IDs: Use a database primary key or immutable customer number as the Integration ID. Do not use email addresses or other mutable values, as changing the ID creates a new profile instead of updating the existing one.
• Pre-create custom attributes: Custom profile attributes must be defined in Talon.One before syncing. Navigate to Account > Tools > Attributes in Campaign Manager to create them.
• Use audience syncs for campaign targeting: For loyalty and promotion campaigns, sync audiences rather than relying solely on profile attributes. This gives you fine-grained control over which customers are targeted.
• Prefer upsert mode for profiles: Since Talon.One automatically creates new profiles and updates existing ones, upsert is the natural choice for profile syncs.
• Add per-application prefixes: If you use multiple Talon.One applications in the same environment, add a prefix to Integration IDs (e.g. app1_cust_123) to avoid profile collisions.

Troubleshooting

Authentication failed: invalid API key

Verify that you are using an Integration API key, not a Management API key. Integration keys are found in Settings > Developer in the Campaign Manager. Ensure the key has not been revoked or expired.

Deployment URL returns connection error

Check that the deployment URL follows the format https://yourcompany.talon.one. Do not include a trailing slash or path suffix. Verify the URL by opening it in a browser — you should see the Talon.One API documentation page.

Audience ID not found (404)

The Audience ID must be the numeric id value returned when creating an audience via the API or visible in the Campaign Manager. It is not the audience name. Navigate to Audiences in Campaign Manager and check the ID column.

Custom attributes not appearing on profiles

Custom attributes must be pre-created in Talon.One before syncing. Navigate to Account > Tools > Attributes and ensure each attribute name matches the destination field name exactly (case-sensitive). Attributes created after the sync are ignored for previously synced records.

Profiles created but not visible in application

Customer profiles are shared across all applications in an environment. However, a profile will not appear in an application’s context until a session or profile update occurs within that application. To make profiles visible, ensure at least one session update is triggered for the application.

Rate limit exceeded (HTTP 429)

Talon.One rate-limits requests to approximately 60 per second per deployment. If multiple syncs run simultaneously, they may exceed this limit. Zeotap retries automatically with backoff, but consider staggering sync schedules or contacting Talon.One to increase your rate limit.

Audience membership changes not reflected in campaigns

After adding or removing audience members, campaign rules that reference the audience will apply on the next customer session update. Changes are not retroactive — they only affect future rule evaluations. Trigger a session update for affected profiles to see immediate results.

Integration ID mismatch between profiles and audiences

Ensure the integration_id used in audience membership syncs matches the integration_id used when creating or updating customer profiles. Mismatched IDs result in audience actions targeting non-existent profiles, which Talon.One silently creates as empty profiles.