Create a Cohort Syncing Integration

This guide walks through the basics of creating a cohort sync integration with Amplitude.

This guide uses a list-based integration in its examples. If you create a property-based cohort sync integration, some steps may differ.

Integration setup

Configure the integration tile that appears on the Amplitude Destinations page after Amplitude validates your integration. You also need to decide between a list-based cohort integration and a property-based cohort integration. For details about each integration type, refer to Receiving behavioral cohorts.

1. From the Integration Portal page (Settings > Developer Portal), click Add New Destination.
2. Choose the target connection from the Select Connection Information dropdown.
3. Choose whether you are building a list-based or property-based cohort integration:
   • List-based cohort integration: A list-based cohort integration works best if the target system represents a cohort as a list of user identifiers. The first sync requires a call to a list creation API, then subsequent calls to the add API and remove API keep the list membership up to date.
   • Property-based cohort integration: A property-based cohort integration works best with systems that represent cohort membership as a custom user property, such as a boolean flag or a tag. Amplitude invokes the update API when cohort membership changes to update the user property. Although you don't need to use the list creation API, you may need to manually create the custom user property.
4. Click Next to configure the destination.

Integration name

The integration name appears on the catalog page. The name must be globally unique across cohort sync integrations.

Configure the cohort sync integration

The configuration page has two sections.

• The Configuration tab is where you configure your payload and what you expect to receive from Amplitude.
• The Testing Integration tab summarizes your configurations, including the Destination Settings form, which previews your integrations, variables, and payload. You can also test your integration functionality from this tab.

The next several sections walk through configuration and testing options.

Set authentication method

Determine how you plan to authenticate the API call between Amplitude and your company.

Click Custom Headers, and choose from the following options:

• No authentication: This option doesn't require an authentication header.
• Basic Authentication: Use API key and API Secret (optional) as authentication headers.
• Authentication Header: Authenticate with API key.
• Bearer Token: Use Bearer Token as an Authorization header.

Create custom fields

These fields collect and replace the $variable declared in the API call payloads. They also build the modal customers use to enable your integration. Fields you add here become required fields when users set up the integration.

• Field Type: Specify the field type, such as String, Single Select, or Button Group.
• Field variable name used in the payload: By default, this matches your authentication choice. For example, if you choose Bearer Token as the authentication method, it's "bearer_token."
• Display name: The name your users view in the setup modal for your integration. By default, this matches your authentication choice. For example, if you choose Bearer Token as the authentication method, it has a placeholder display name called "Bearer Token."
• Add New Custom Field: If you need to add another identifier required for the payload, you can add custom fields such as String, Single Select, and Button Group.

Map fields

Map fields to specify how Amplitude fields connect to the fields in your system. The value of the mapping replaces item_template in the payloads.

When you configure Mapping Fields in the Integration Portal, users of your integration view a Mappings section in their Destination Settings. This section lets users select any Amplitude user property to map to a field in your destination system. This configuration also supports custom user identifiers.

• Mapping Field Display Name: Amplitude recommends setting this as "Key," "Identifier," or "User ID Mapping."
• Amplitude Mapping Field: The field name in Amplitude. For example, user_id_field_amplitude.
• Field Type: Either "String" or "Single Select."
• Display name: This is fully customizable, so use something descriptive. For example, User ID or Email.
• Add New Mapping: Add more mappings if required, such as String, Single Select, or Button Group.

Slugify Amplitude cohort name

You can slugify cohort names to standardize them. This option helps if your system doesn't support special or non-ASCII characters. Slugification converts your cohort name to a URL slug by replacing Unicode special characters and spaces with ASCII characters and hyphens. This feature works only when the $amplitude_cohort_name variable appears in the endpoint payload. The slugify rule is as follows:

• Convert the original cohort name to normalization form KD (NFKD), which is compatibility decomposition.
• Substitute hyphens for the characters except for the alphabets (a-z, A-Z), the numbers (0-9) and the underscores (_).
• Limit the slug to 100 characters.

List creation endpoint

You need to call three APIs for a list-based integration. The first API is the list creation endpoint. When a cohort syncs for the first time, Amplitude calls this API and creates a list on your platform. Amplitude expects your app to send a response with the unique identifier for listID. Amplitude stores the listID from that response and uses the ID as part of the payload for list updates.

• URL Endpoint: Define the endpoint, such as https://api.yourapp.com/list. Choose which method to use in the call.
• API payload to send to the destination: Customize this payload to fit your needs.
• Path to List ID in the response: N/A

Errors for the list creation endpoint

Add error status codes and error messages for every endpoint so end users can debug and get faster help.

Expand Error Classifications, and click Add New Error to add more status codes. Amplitude recommends including as many status codes and sub-error codes as you need. These codes and messages make debugging faster for your end users.

1. Amplitude recommends using sub error codes if you use the same status code for multiple errors.

Here are some common examples of status codes that most partners include:

• 200: Success
• 400: Invalid request
• 401: Unauthorized (bad api_key)
• 404: Invalid User ID
• 429: Throttling/rate limiting

Amplitude suggests giving a clear Failure Reason (Description) and Error Message in case cohort sync fails. Clear messages improve your end user's experience and can help reduce support issues.

Add users endpoint

Amplitude calls the add users API every time a cohort syncs from Amplitude to your app. This sync can run hourly or daily. The call calculates the difference between the current cohort size and the last successful sync.

• URL Endpoint: The URL can include a $list_Id placeholder, but this placeholder isn't required. You can design your API to place the list ID in the payload instead. Example: https://your.domain/lists/$listId/add.
• API payload to send to the destination: Customize this payload and define whether the payload is a batch. The $items variable is the important key. The contents of An array of items that replaces the $items variable in the payload replace this variable.

The $items variable usually identifies every user in a cohort. For example, a sync may add 20 new users to an existing cohort. The Batch object contains a collection, such as a list of 20 users, and Amplitude sends those 20 objects to your endpoint. Your payload might look like this:

json { "userIds": $items, "context": { "integration":{ "name": "Amplitude Cohort Sync", "version": "1.0.0" } } }

• Maximum number of items in each API call (batch size): The default is 10,000, but you can specify this. Amplitude's recommendation is to have a 10,000 user per cohort batch.
• An array of items that replaces the $items variable in the payload: Specify the format of object that replaces the $item variable in the payload. For example, "$user_id_field_amplitude".

Avoid rate limiting if possible. If you have rate limits, such as 90 requests per second, make them explicit in your user documentation. Amplitude sends 4 requests in parallel, with each request containing up to 10,000 users.

Errors for add users endpoint

Instead of creating every status code, failure reason, error message, and sub-error code again, Amplitude recommends using the same set of error codes from your list creation endpoint. Select Copy errors from other endpoints and select an endpoint with configured errors.

Remove users endpoint

Amplitude calls the remove users API every time a cohort syncs from Amplitude to your app. This sync can run hourly or daily. The call calculates the difference between the current cohort size and the last successful sync.

• URL Endpoint: The URL can include a $listId placeholder, but this placeholder isn't required. You can design your API to place the list ID in the payload instead. Example: https://your.domain/lists/$listId/remove.
• API payload to send to the destination: Customize this payload and define whether the payload is a batch. The $items variable is the important key. The contents of An array of items that replaces the $items variable in the payload replace this variable.

The $items variable usually identifies every user in a cohort. For example, a sync may remove 20 users from an existing cohort. The Batch object contains a collection, such as a list of 20 users, and Amplitude sends those 20 objects to your endpoint. Your payload might look like this:

json { "userIds": $items, "context": { "integration":{ "name": "Amplitude Cohort Sync", "version": "1.0.0" } } }

• Maximum number of items in each API call (batch size): The default is 10,000, but you can specify this. Amplitude's recommendation is to have a 10,000 user per cohort batch.
• An array of items that replaces the $items variable in the payload: Specify the format of object that replaces the $item variable in the payload. For example, "$user_id_field_amplitude".

Errors for remove users endpoint

Instead of creating every status code, failure reason, error message, and sub-error code again, Amplitude recommends using the same set of error codes from your list creation endpoint. Select Copy errors from other endpoints and select an endpoint with configured errors.

Preview & test endpoint

Before submitting your configuration for review, test the mock payload that you expect to receive from Amplitude. In the Testing tab, follow these steps to preview and test your configuration.

In the Testing tab, the Destination Settings form matches what users of your integration view. This form controls the parameters you've defined in the payload headers.

To generate users, upload a CSV or click Regenerate to generate users based on your configuration. The CSV must have an Operation column with either add or remove. Any parameters used in the List Creation payload must be the same across all rows in the CSV. The CSV must also have columns for each parameter used.

Here is a sample CSV for the default configuration:

operation,user_id_field_amplitude,amp_cohort_name,amp_cohort_id
add,user123,Unified Cohort,unified_cohort_001
add,user456,Unified Cohort,unified_cohort_001
remove,user789,Unified Cohort,unified_cohort_001
add,john.doe@example.com,Unified Cohort,unified_cohort_001

Check the parameters table to make sure the configuration accounts for all variables and resolve any errors. Ensure that all declared fields are non-empty.

• DECLARED: All declared variables in the "Authentication calls, Custom Fields and Mapping Fields section."
• USED: All variables used in the list users endpoint, add users endpoint, and remove users endpoint.
• PRE-DEFINED: Pre-defined variables that Amplitude replaces values for.

To modify the headers, use the Destination Settings form on the Configuration and Testing tabs.

Check your headers and payloads. When ready, click Test Endpoint to send a test API call to the predefined endpoint. The response or error appears for debugging.

After you click Test Endpoint, you should get a success response. Retrieve the $list_id; Amplitude uses the $list_id for the "Add Users Endpoint."

The {listId: $list_id} is the expected response for list creation API call. To change the structure, change the Path to List ID in the response value in the list creation configuration.

Use the $list_id you retrieved to test the add users and remove users endpoints.

You can also test end to end with the Test Endpoint button in the Test Integration section. This button automatically runs all necessary tests.

Release internally

To test in your org, click Release Internally. This enables anyone within your org to use the integration you defined. The integration becomes available immediately.

Submit your integration

After you finalize your testing, click Submit to submit your integration to the Amplitude team. The review process takes about one week. When Amplitude approves your integration, Amplitude notifies you by email and your integration tile appears in the Destination section of Amplitude.