Search documentation...

ChangelogBook a demoSign up


Supported syncing

Sync TypeDescriptionSupported Sync ModesAPI reference
ObjectsSync records to objects such as Accounts, Organizations or Users in VitallyUpsert, Update, InsertObject endpoints
EventsSync records as events to Vitally.UpsertEvents docs

For more information about sync modes, refer to the sync modes docs.

Connect to Vitally

Go to the Destinations overview page and click the Add destination button. Select Vitally and click Continue. You can then authenticate Hightouch to by entering the following fields into Hightouch:

  • Region: Either EU or US.
  • Analytics API Token: You only need to enter this if you plan on syncing events.
  • REST API Token: You only need to enter this if you plan on syncing objects.

Follow these instructions to generate tokens.

  1. Log into your Vitally account, click the wheel icon on the bottom sidebar.

    Vitally setup

  2. Under Data Management, select the Integrations option.

    Vitally setup

  3. For the Analytics API Token, select the Vitally Analytics API card. Otherwise skip to step 6 for the REST API Token.

    Vitally setup

  4. Toggle on the integration.

    Vitally setup

  5. Click the Integrate via HTTPS API tab and copy the API KEY. This is the Analytics API Token you need to enter in Hightouch.

    Vitally setup

  6. For the REST API Token, select the Vitally REST API card.

    Vitally setup

  7. Toggle on the integration and click to generate the API Key.

    Vitally setup

  8. Copy the Basic Auth Header once it's generated to use in Hightouch. This is the REST API Token you need to enter in Hightouch.

    Vitally setup

Once you've entered the relevant token or tokens, click Continue and enter a descriptive name for your destination to complete setup.

Sync configuration

Once you've set up your Vitally destination, have a model to pull data from, and have a clear idea of the data you want to sync, you can set up your sync. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Vitally destination you want to sync to.

Syncing objects

Hightouch supports syncing to account, organization, and user objects in Vitally.

Record matching

To match rows from your model to objects in Vitally, you need to select the model column that contains values that match the External ID field in Vitally. When syncing users, you can also match on Email.

Refer to the record matching docs for more information.

Field mapping

Hightouch lets you sync object fields via field mapping. You can map data from any of your model columns to any of an object's default fields. Ensure the data type of your model column matches the data type of field you want to sync to in Vitally. For example, a Vitally text field expects a model column with the string data type.

When using Upsert or Update mode to sync users, if you match on Email, you need to map both the External ID and either Account IDs or Organization IDs. Otherwise, Hightouch displays a Required field error and a Must specify at least one of: accountIds or organizationIDs error.

Hightouch sync configuration

If you match users on External ID, you only need to provide either Account IDs or Organization IDs. Otherwise, Hightouch displays a Must specify at least one of: accountIds or organizationIDs error.

Hightouch sync configuration

Vitally accounts, organizations, and users objects contain an editable traits attribute to store custom key/value pairs. This is useful for storing information like a customer's plan, number of licenses, name, etc.

To properly sync traits to Vitally, you need to format the traits field as an object data type rather than a string. You can create an object of all the fields you want to update, and then map them to traits. An example traits attribute for an organization object could look like this:

	"organizationId": "Id_value",
	"organizationName": "Name_value"

You can use template mapping to create objects like this in your sync configuration. In the following example screenshot, the template uses this Liquid function

{{ | json_construct : 'organizationName', row['organizationName'] }}

to create an object where the key's name is organizationName and the value is the row's organizationName column.

Hightouch sync configuration

For more information, refer to the Vitally's API documentation.

You can sync columns from your model to existing traits in Vitally and/or create new ones by adding them directly to the traits object in your Hightouch sync.

Delete behavior

The delete behavior you select dictates what to do when a row no longer appears in your model's query results. You have the following options:

Do nothingKeep the object in Vitally with all its mapped properties
DeleteDelete the object in Vitally and all its mapped properties

Syncing events

Hightouch supports syncing product events in Vitally. Vitally's API requires the following event parameters:

  • event: the name or type of event
  • timestamp: the time the event was generated
  • message_id: a unique ID for the event

And at least one of:

  • user_id: the ID of the user that 'owns' the event
  • account_id: the ID of the account that 'owns' the event

The sync configuration form ensures all these are set and provides some additional options.

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

Event name

Providing an event name is required to send an event to the Vitally's API. You can either provide a static value or select to use a column from your model. Hightouch syncs the static or column value as the event parameter the API requires.

Event timestamp

You can optionally select a column that contains timestamps of when events occurred. If this field is empty, Hightouch uses the time the event arrives at the server. Hightouch syncs the timestamp as the timestamp parameter the API requires.

Field mapping

Field mapping is where you select which event parameters you want to send to the Vitally's API. The API requires you to map at least one of the following fields in order to save your sync.

  • Account ID
  • Organization ID
  • User ID

Hightouch sync configuration

You can also include data to sync as custom event fields in Vitally.

Hightouch sync configuration

Tips and troubleshooting

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

Must specify at least one of: accountIds, organizationIDs, user_id

You may receive an error like this in the Hightouch UI if you don't include all necessary values in your sync. Consult the field mapping section of your relevant sync type to learn more.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Sep 22, 2023

On this page

Supported syncingConnect to VitallySync configurationSyncing objectsSyncing eventsTips and troubleshootingCommon errorsLive debuggerSync alerts

Was this page helpful?