Overview

Projects and Profiles

Before we begin, we would like to talk about two new paradigms that we introduced on the Batch platform for Emails.

Projects group Android/iOS apps, Websites and Emailing together in a single entity. Projects have their own identifier for use with our new project-level APIs (called the Project key).

Data used to be siloed between different apps: projects remove that limitation by introducting profiles.

Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom user ID. They can also store a profile's email and email subscriptions.
This allows Batch to support more complex and cross-channel lifecycles: it is now possible to message a user on a channel even though its profile data is fed from another one.

For example, this use case is now supported:

• A user creates an account from your Android app. You use the Android SDK to set a Custom User ID and add Custom Attributes.
• You collect their email and use the Profile API to tell Batch about it.
• This user then logs in on your website, which sets the Custom User ID.
• The user performs some action on your website, which you send to Batch using the Custom Events
• If some action is triggered in your backend, changing that user's profile or triggering an event, you can call the Profile API to update the user's profile.

You will now be able to create an email automation or campaign, which automatically uses the data from the app, website and profile API and reacts to both events the user did on your website and tracked by your backend thanks to the Custom User ID.

Using Project APIs

Prerequisites

Before sending your first call to our API, make sure you have:

• Your REST API key.
• Your Project Key.

You will find these IDs in your project settings, on Batch dashboard (⚙️ Settings → General). Please note you need to be the manager of the account to see the REST API key.

Please make sure that you keep your REST API key secret: it is sensitive and should not be shared in any form. You should never use it in client apps to call APIs from there as it would easily be extractable. Our support team will never ask for your REST API key.

Request headers and authentication

Three headers are required to use the API:

• Content-Type must be set to application/json.
• The REST API key should be in the Authorization header, prefixed by Bearer . Example: Authorization: Bearer EC3DBFXPZ67RTCDEF. If you are logging your requests, you should exclude this header from the logs.
• Your Project key goes in the X-Batch-Project header. Example: X-Batch-Project: project_2bcdf83eubjhfdmk78jf.

Example:

curl --request POST \
  --url https://api.batch.com/2.0/audiences/create \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer your_rest_key_here' \
  --header 'X-Batch-Project: your_project_key_here' \
  --data '{
  "name": "AUDIENCE_NAME",
  "display_name": "The audience description",
  "type": "custom_ids"
}'

Note: You will find cURL examples for the API endpoints in the OpenAPI schema

API Description

The APIs have their schema available in the OpenAPI 3.1 format: View it online.

You will also find step-by-step documentation on how to use those APIs in this documentation's sidebar.

Differences with v1 APIs

APIs on the 2.0 and higher endpoints work differently than the previous APIs:

• The REST API key does not use X-Authorization anymore, but the standard Authoriaztion header
• The Project key is in a HTTP header rather than in the route
• The 2.x APIs are not RESTful by design: endpoints are structured differently and will use GET/POST methods only
• An OpenAPI schema is available