ClientSuccess

Sync client, contact, and contract data from your warehouse to ClientSuccess, the customer success management platform. Keep your customer success team’s account data, contact records, and contract details up to date by pushing enriched data directly into ClientSuccess.

Prerequisites

• A ClientSuccess account with API access enabled
• An API key with read/write permissions to the objects you intend to sync
• We recommend creating a dedicated API user account named “API Access” for integration use

Permissions

Your API key must have access to the following based on the object type you are syncing:

• Clients: Create, update, and search client records
• Contacts: Create, update, and search contact records
• Contracts: Create, update, and search contract records

To generate an API key, navigate to Global Settings > API Credentials in your ClientSuccess account.

Authentication

ClientSuccess uses API Key authentication.

1. Log in to your ClientSuccess account
2. Navigate to Global Settings > API Credentials
3. Generate a new API key (or copy an existing one)
4. Paste the API key into the API Key field in Zeotap

Your API key is sent via the Authorization HTTP header with each request.

Configuration

ClientSuccess does not require additional configuration fields beyond authentication. The API base URL (https://api.clientsuccess.com/v2) is used automatically.

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

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

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Client

Contact

Contract

How It Works

Insert Mode

For Client and Contact objects, Zeotap uses the ClientSuccess Bulk Create endpoint (POST /v2/client/bulk or /v2/contact/bulk) to create records in batches of up to 100. For Contract objects, records are created individually via POST /v2/contract since the bulk endpoint is not available.

Update Mode

Each row is sent individually to the ClientSuccess Update endpoint:

• Clients: PUT /v2/client/{uuid}
• Contacts: PUT /v2/contact/{uuid}
• Contracts: PUT /v2/contract/{uuid}

The uuid field must be present in every row, containing the ClientSuccess record UUID to update.

Upsert Mode

Zeotap uses the native ClientSuccess Upsert endpoint (POST /v2/{object}/upsert) for each record. The API matches on the object’s natural key (e.g., externalId for clients, email for contacts) and creates or updates accordingly.

Error Handling

• Requests are retried up to 3 times with exponential backoff on transient errors (429, 5xx)
• Rate limit responses (HTTP 429) respect the Retry-After header when present
• Per-record failures are tracked and reported in sync run details
• Bulk insert failures are reported with the API error message

Rate Limits

ClientSuccess does not publish explicit API rate limits. Zeotap uses conservative batching (100 records per bulk request) and sequential processing to avoid overloading the API. If you encounter rate limiting (HTTP 429), Zeotap automatically retries with exponential backoff.

Best Practices

• Use upsert mode when possible: The native upsert endpoint handles deduplication automatically, reducing the risk of creating duplicate records
• Map externalId for clients: This allows ClientSuccess to match existing records during upsert operations and enables cross-system data linking
• Provide UUIDs for update mode: Update operations require the ClientSuccess record UUID. Ensure your source data includes these identifiers
• Create a dedicated API user: ClientSuccess recommends creating a separate user account named “API Access” for API integrations
• Map clientId for contacts and contracts: Contacts and contracts are associated with a parent client via the client UUID

Troubleshooting

Authentication failed: invalid API key

Verify your API key in ClientSuccess under Global Settings > API Credentials. Ensure the key has not been revoked or regenerated. If you recently regenerated the key, update it in Zeotap.

Update failed: uuid is required

When using update sync mode, every row must include the ClientSuccess record UUID in the uuid field. Ensure your source data contains the ClientSuccess record UUIDs and that the field is correctly mapped.

Records not matching during upsert

The ClientSuccess upsert endpoint uses the object’s natural key for matching. For clients, ensure the externalId or name field is populated. For contacts, ensure the email field is included. If matching fails, a new record will be created.

Bulk insert returning errors

The bulk create endpoint (POST /v2/{object}/bulk) accepts an array of records. If any required field is missing (e.g., name for clients, clientId for contacts), the entire batch may fail. Check that all required fields are mapped in your sync configuration.

Contact sync failing with missing clientId

Contacts in ClientSuccess must be associated with a parent client account. Ensure the clientId field is mapped to a valid ClientSuccess client UUID. You may need to sync client records first before syncing contacts.

Contract dates not updating correctly

Contract date fields (startDate, endDate) must be in YYYY-MM-DD format. Ensure your source data provides dates in this format, or use a field transform to convert them before syncing.