Partner cohort import integration

The Partner Cohort Import integration feature allows our partners to integrate with Braze to send over cohorts of users that were generated within the partner’s application.

Cluster URLs

Braze hosts our application on multiple clusters throughout the US and EU. The URL for the import endpoints will be different depending on the cluster the client’s company instance is hosted on:

Endpoint URLs

In addition to the top-level URLs being cluster-specific, each endpoint is also partner-specific. For example, when importing to our US01 cluster, the URL would have the format https://rest.iad-01.braze.com/partners/[partner_name]/…, where [partner_name] is typically the name of the partner’s business. Specifics for each endpoint are outlined in the following sections.

Authentication

To import cohort data into Braze, there are two authentication keys required.

Partner API key

The Partner API Key identifies the integration partner and authenticates the request as being valid for import. The key should be included in the body of the request in the partner_api_key field.

When setting up the integration in the partner’s application, the client should be asked to specify their Braze cluster so the integration knows which cluster URL and partner API key to use when importing data.

Braze will provide the Partner API Key(s) to the partner prior to the partner beginning integration development. In general, we will provide a single key that is valid for all US clusters, and another key that is valid for our EU cluster.

Client data import key

The client data import key identifies the client workspace into which the cohort should be imported. The key should be included in the body of the request in the client_secret field.

This key is generated in the client’s dashboard in the integrations settings for the partner. When setting up the integration in the partner’s application, the client should be asked to specify their data import key so the integration knows which client and workspace to send data to.

API endpoint specifications

Cohort name endpoint

The Cohort name endpoint can be used to specify the name of a cohort based on its ID. This endpoint should be called whenever a cohort is initially exported to Braze, or when the name of a cohort already known to Braze is changed.

Example request:

POST: https://rest.iad-01.braze.com/partners/[partner_name]/cohorts

1
2
3
4
5
6
7
{
	"partner_api_key" : "123456-1234-1234-12345678",
	"client_secret" : "234567-2345-2345-23456789",
	"cohort_id" : "[some unique identifier generated by the partner]",
	"name" : "Name of the cohort that will appear in the Braze dashboard",
	"created_at" : "2021-01-21T19:20:30+05:00"
}

User cohort endpoint

The User cohort endpoint allows for specifying which users have been added to or removed from a particular cohort. This endpoint should be called when a cohort is refreshed. Only users who have newly entered the cohort or who have left the cohort since the last refresh should be sent to Braze.

Example request:

POST: https://rest.iad-01.braze.com/partners/[partner_name]/cohorts/users

1
2
3
4
5
6
7
8
{
	"partner_api_key" : "123456-1234-1234-12345678",
	"client_secret" : "234567-2345-2345-23456789",
	"cohort_id" : "[some unique identifier generated by the partner]",
	"cohort_changes" : "[
	   {"user_ids": ["test_user_1", "test_user_2"]}
	]"
}

Rate limiting

In addition to the maximum of 1,000 user IDs per request in the user cohort endpoint, these endpoint requests are rate-limited to 250,000 requests per hour.

Cohort filter

Braze will add a filter that allows a dashboard user to include or exclude users from a targeted audience if they are in a partner cohort. The filter will provide a dropdown list of the names of all cohorts known to Braze for that client. This filter will only be visible to clients that partner and Braze have agreed to partner with in this integration.

Troubleshooting

Refer to the following table for errors codes specific to the Cohort Import endpoints, and how to troubleshoot them.

For additional troubleshooting, refer to Errors & Responses, which covers the various errors and server responses that can come up while using the Braze API.