Vitally

Sync customer success data to Vitally — including accounts, users, organizations, notes, tasks, and conversations. Zeotap pushes data from your warehouse into Vitally via their REST API, enabling you to enrich customer health scores, automate success workflows, and maintain a unified view of your customer relationships.

Prerequisites

• A Vitally account with REST API access enabled
• A REST API secret token generated from the Vitally dashboard
• Your Vitally region (US or EU). US accounts also require a tenant subdomain (e.g. acme for https://acme.rest.vitally.io). EU accounts use the shared https://rest.vitally-eu.io host and do not need a subdomain.

Authentication

Vitally uses API Token authentication via HTTP Basic Auth.

1. Log in to your Vitally account
2. Navigate to Settings > Integrations > REST API
3. Copy your existing Secret Token, or click Generate to create a new one
4. Paste the token into the API Token field in Zeotap
5. Select your Region (US or EU)
6. If you are on the US region, enter your Subdomain (e.g., if your API URL is acme.rest.vitally.io, enter acme)

Keep your API token secure. It provides full access to your Vitally account data via the REST API. Do not share it in publicly accessible locations.

Configuration

Target Settings

When Object Type is “Account”

Account records are created or updated in Vitally using the externalId as the unique identifier. Custom fields are sent as traits and merged with existing traits on the account. The name field is required when creating new accounts.

When Object Type is “User”

User records are created or updated using the externalId. Users must be associated with at least one account (via accountId or accountIds) or organization (via organizationId or organizationIds). Custom fields are sent as traits.

When Object Type is “Organization”

Organization records are created or updated using the externalId. Organizations group multiple accounts together and support custom traits.

When Object Type is “Note”

Notes are created on an account. Each note requires an accountId to specify which account the note belongs to. Notes support a subject and body field.

When Object Type is “Task”

Tasks are created on an account. Each task requires an accountId and supports a subject and description via the body field.

When Object Type is “Conversation”

Conversations are created on an account. Each conversation requires an accountId and supports a subject and body field.

Supported Operations

Sync Modes

Audience Sync Modes

Vitally does not have a list or segment membership API — segments are computed dynamically based on account and user properties. Use traits on accounts or users to control segment membership indirectly.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

How It Works

Account, User, and Organization Syncs

1. Zeotap extracts records from your model or audience
2. Each record is sent individually to the Vitally REST API
3. For insert mode, records are created via POST /resources/{accounts|users|organizations}
4. For upsert and update modes, records are written via PUT /resources/{accounts|users|organizations}/{externalId} — Vitally accepts the externalId as the :id path segment and upserts the record by that identifier
5. Additional mapped fields beyond the standard fields are sent as custom traits in the traits object
6. Traits are merged with existing traits — setting a trait value to null removes it

Note, Task, and Conversation Syncs

1. Zeotap extracts data from your model
2. Each record is sent individually to the appropriate Vitally REST API endpoint via POST
3. Records are created on the account specified by accountId
4. The subject and body fields populate the record content
5. Notes, tasks, and conversations are append-only on an account — the update sync mode is not supported for these object types, and upsert falls back to POST (create)

Rate Limits

Vitally enforces the following rate limits on their REST API:

• Default: 1,000 requests per minute using a sliding window
• Response headers: RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset are included in every response

Zeotap automatically handles rate limiting with exponential backoff and respects the RateLimit-Reset header. Since each record is sent individually (no batch endpoint), large syncs may take longer due to rate limit pacing.

Best Practices

• Use the Account object type to push customer data, revenue metrics, and health indicators into Vitally
• Use the User object type to sync end-user profiles with contact details and role information
• Map custom fields as traits to enrich Vitally’s health scoring and segmentation capabilities
• Use consistent externalId values between your warehouse and Vitally to avoid duplicate records
• For US region accounts, ensure your subdomain is correctly configured — an incorrect subdomain results in API connectivity errors
• Start with a small sync to verify field mapping before running full syncs
• Use the Upsert sync mode to keep records current without creating duplicates
• Send organizationId with accounts to group them under the correct organization hierarchy

Troubleshooting

Authentication failed (HTTP 401)

Verify your API token is valid and has not been revoked. Tokens can be managed in Settings > Integrations > REST API in Vitally. Ensure you are using the REST API token, not the Analytics API token — they are different.

Wrong region or subdomain

If you receive connectivity errors, verify your region setting matches your Vitally account. US accounts require a subdomain (e.g., acme for acme.rest.vitally.io). EU accounts use rest.vitally-eu.io and do not need a subdomain.

Records not appearing in Vitally

Ensure the externalId field is mapped and contains non-empty values for accounts, users, and organizations. For notes, tasks, and conversations, verify the accountId is a valid Vitally-assigned account ID (not an external ID).

Duplicate records

Duplicates occur when different externalId values refer to the same customer. Ensure your source data uses consistent identifiers. Vitally uses externalId as the primary deduplication key for accounts, users, and organizations.

Rate limit errors (HTTP 429)

Vitally limits REST API requests to 1,000 per minute. Zeotap retries automatically with exponential backoff. For large syncs with many records, the sync will pace itself automatically. Check the RateLimit-Remaining response header to monitor usage.

Custom traits not updating

Traits are merged with existing values on each update. To remove a trait, explicitly set its value to null in your source data. Verify that trait keys do not conflict with reserved field names like externalId, name, or email.

User creation fails — missing account or organization

When creating users, Vitally requires at least one of accountIds or organizationIds. Map either accountId (single account) or organizationId (single organization) to associate the user. These must be Vitally-assigned IDs, not external IDs.

Note or task not linked to account

Notes, tasks, and conversations require a valid accountId field. This must be the Vitally-assigned account ID (a UUID format), not the externalId you use for account syncs. You can find account IDs in the Vitally UI or by querying the accounts API.