Configure destinations for Zendesk

Zendesk is a service-first customer relationship management (CRM) application. Companies use Zendesk to improve customer relationships by providing support, chat, and community services that span channels.

Important

Zendesk is removing API tokens as an authentication method . Zendesk does not allow new API tokens to be created after October 27, 2026, and deactivates all remaining API tokens on April 30, 2027.

Every Zendesk destination and courier must use an OAuth client credential by April 30, 2027. A destination or courier that still uses an API token (legacy) credential stops working when Zendesk deactivates its API token. Switch each one to an OAuth client credential before that date.

To switch, see Switch from an API token to an OAuth client.

Amperity may be configured to create or update user records in Zendesk by using the Zendesk Users API to create or update users . Use this connector to deliver a better customer support experience by pre-populating Zendesk user records with customer records from Amperity, including:

• Order history

• Loyalty status

• Satisfaction survey results

• Shopping preferences

• and more

Use this data to show customer support representatives information related to product recommendations, next best actions, and likelihood of churn.

Note

Creating or updating records are rate limited to a maximum of 100 users per second.

Note

Amperity automatically sets all user records to verified when they are sent to Zendesk. This prevents Zendesk from sending verification emails to users whose records are created or updated by Amperity.

Get details

Review the following details before configuring credentials for Zendesk and before configuring Amperity to send email lists to Zendesk.

	Credential settings Amperity supports two credential types for Zendesk: OAuth client authenticates with a Zendesk OAuth client, using a client ID and a client secret. Amperity selects this credential type by default when you add a credential. Use it for every new Zendesk credential. API token (legacy) authenticates with a Zendesk API token and the email address of the user who created it. OAuth client Client ID Required Required. The client ID of the OAuth client in Zendesk Admin Center. Client secret Required Required. The client secret of the OAuth client in Zendesk Admin Center. API token (legacy) API token Required Required. Your brand’s Zendesk API token. Email address Required Required. The email address for the Zendesk API user.
	Required configuration settings Subdomain Required Required. The subdomain for your brand’s Zendesk account. For example: “socktown” is the subdomain for “socktown.zendesk.com”. Note Both credential types require Subdomain. Amperity sends every request to the Zendesk account that Subdomain names, and an OAuth client credential also requests its access tokens there. When Subdomain is empty, an OAuth client credential fails the connection test and every run with the message “Subdomain is required for Zendesk OAuth authentication.”
	Required fields for Zendesk Be sure to send all fields required by Zendesk. Important Fields must exist in Zendesk and should follow a “user_fields.[field_name]” naming pattern, where “field_name” is the name of the field that is sent to Zendesk from Amperity. The name field and either the email or external_id field must be included. Note Records that are missing required fields are not sent to Zendesk. Each invalid record is reported as a failure in the workflow. Values for states should be 2 uppercase letters only. Phone numbers should start with “+1” and contain only digits. Floating point numbers must be in DECIMAL(10,2) format. From within Zendesk verify that audience data has been loaded and is usable by all of the use cases you want to use within Zendesk to build better customer experiences.

Configure credentials

Configure credentials for Zendesk before adding a destination.

Amperity supports the following credential types for Zendesk:

1. OAuth client

2. API token

To move a destination that uses an API token to an OAuth client, see Switch from an API token to an OAuth client.

An individual with access to Zendesk should use SnapPass to securely share “client ID” and “client secret” (or “email address” and “API token”) details with the individual who configures Amperity.

OAuth client

A Zendesk administrator creates the OAuth client in Zendesk Admin Center, under Apps and integrations > APIs > OAuth clients:

1. Sign in to Zendesk as a dedicated service account user, not as a person. Zendesk attributes every action Amperity takes with the OAuth client to the user who created it, so a client created under a person’s account can stop working later, for example after that person leaves.

2. Create a new OAuth client, and set its client kind to Confidential. Amperity uses the client credentials grant, which Zendesk allows only for confidential clients. A public client fails.

3. Leave the redirect URL empty. The client credentials grant does not use one.

4. Set Allowed scopes to read users:write, or leave it empty to allow all scopes. Amperity requests both of these scopes, and fails when the OAuth client does not allow them.

5. Copy the client ID and the client secret.

To configure credentials using an OAuth client

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Create credential dialog box, do the following: From the Plugin dropdown, select “Zendesk”. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination. The Credential type dropdown selects OAuth client by default. Keep it selected.
	Enter the client ID and client secret of the OAuth client, and then click Save. Client ID Required Required. The client ID of the OAuth client in Zendesk Admin Center. Client secret Required Required. The client secret of the OAuth client in Zendesk Admin Center.

API token

An API token (legacy) credential uses an API token that already exists in Zendesk. Use an OAuth client credential for every new Zendesk credential.

To configure credentials using an API token

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Create credential dialog box, do the following: From the Plugin dropdown, select “Zendesk”. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination. From the Credential type dropdown, select API token (legacy).
	Enter the API token and the email address of the user who created it, and then click Save. API token Required Required. Your brand’s Zendesk API token. Email address Required Required. The email address for the Zendesk API user.

Switch from an API token to an OAuth client

Move each Zendesk destination from an API token (legacy) credential to an OAuth client credential before Zendesk deactivates API tokens on April 30, 2027.

To switch a destination to an OAuth client

1. Create an OAuth client in Zendesk Admin Center, and then add an OAuth client credential.

2. Open the destination for editing, and confirm that Subdomain is set to the subdomain of your Zendesk account.

3. In the Credential section, click Edit. From the Credential type dropdown, select OAuth client, select the credential you added, and then click Save.

4. Test the connection, and then save the destination.

Add destination

Use a sandbox to configure a destination for Zendesk. Before promoting your changes, send a sample audience, and then verify the results in Zendesk. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for Zendesk

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for Zendesk, do one of the following: Click the row in which Zendesk is located. Destinations list alphabetically and you can scroll up and down the list. Search for Zendesk. Start typing “zen”. The list filters to show only matching destinations. Select “Zendesk”.
	Select the credential for Zendesk from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Subdomain Required Required. The subdomain for your brand’s Zendesk account. For example: “socktown” is the subdomain for “socktown.zendesk.com”.
	After configuring this destination users may use: Orchestrations to send query results Orchestrations and campaigns to send audiences Orchestrations and campaigns to send events
	Validate the audience with Zendesk by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Zendesk. Send the sample audience to Zendesk and verify the sample audience is correct in Zendesk. Make adjustments if necessary. Only send full audiences after validation is complete.

Workflow actions

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

	You may receive a notifications error for a configured Zendesk destination. This appears as an alert in the notifications pane on the Destinations tab. If you receive a notification error, review the details, and then click the Workflow job link to open this notification error in the Workflows page.
	On the Workflows page, review the individual steps to determine which steps have errors that require your attention, and then click Show Resolutions to review the list of workflow actions generated for this error.
	A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Zendesk, including: Invalid credentials
	Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Authentication failures

A 401 or 403 response means that Zendesk rejected the credential. Amperity reports either response as invalid credentials, with the message “Failed to authenticate to Zendesk. Please check your credentials and try again.”, and the workflow shows the Invalid credentials action. This applies to both credential types. For an OAuth client credential, see Credential error messages.

For an API token (legacy) credential, Amperity uses two configuration settings–the Zendesk User API token and the email address of the administrator who created the token–to build a credentials string that is added to the request authorization header. The format for the credentials string is:

{email_address}/token:{api_token}

For an API token (legacy) credential, a 401 or 403 response indicates that the credentials string does not have the correct information. This could be for a number of reasons, including:

• The wrong values for email address or API token are configured in Amperity.

• The API token was deleted in Zendesk.

• The email address for the user who generated the API token is no longer a valid email address within Zendesk or is not associated with a user who has permission to access the Zendesk Users API.

To resolve this error for an API token (legacy) credential, switch the destination to an OAuth client credential, as described in Switch from an API token to an OAuth client. Zendesk does not allow new API tokens to be created after October 27, 2026, so a deleted or deactivated API token cannot be replaced with a new one.

If the email address or API token was mistyped and the API token still exists in Zendesk, correct the credential instead:

1. Open the Amperity Credentials page in a new tab.

2. Verify that the user who created the API token still has access to the Zendesk Users API.

3. Update the email address or API token in the API token (legacy) credential.

4. Return to the workflow action, and then click Resolve to retry this workflow.

Invalid credentials

The credentials that are defined in Amperity are invalid.

To resolve this error, verify that the credentials required by this workflow are valid.

1. Open the Credentials page.

2. Review the details for the credentials used with this workflow. Update the credentials for Zendesk if required.

3. Return to the workflow action, and then click Resolve to retry this workflow.

Credential error messages

Testing the connection or running a workflow returns one of the following messages when Zendesk rejects a credential, or when an OAuth client credential cannot be used:

Message	What to do
Failed to authenticate to Zendesk. Please check your credentials and try again.	Zendesk returned a 401 or 403 response, either to a token request or to a Users API request. For an OAuth client credential, copy the client ID and client secret from Zendesk Admin Center into the credential again, and confirm that the user who created the OAuth client still has access to Zendesk. For an API token (legacy) credential, confirm that the API token still exists and that the user who created it still has access to Zendesk.
The Zendesk OAuth client’s Allowed scopes don’t include the scopes this connector requires (“read users:write”). Update the Allowed scopes on the OAuth client in Zendesk Admin Center and try again.	In Zendesk Admin Center, set Allowed scopes on the OAuth client to read users:write, or leave it empty.
Subdomain is required for Zendesk OAuth authentication.	Set Subdomain to the subdomain of your Zendesk account.
Any other error from Zendesk’s token request, such as unauthorized_client or invalid_grant	Amperity does not translate these errors into one of the messages above. Confirm that the OAuth client is a Confidential client, and then copy the client ID and client secret into the credential again.