# API - Customer Engagement Platform

<figure><img src="https://38998153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCL8wF0y1T2vLnm3yR2MW%2Fuploads%2FbLd37WcevK3aEC2azxaz%2FPushAPI.png?alt=media&#x26;token=148029ec-bda2-4710-9425-1ad9f70d1516" alt=""><figcaption></figcaption></figure>

### Projects and Profiles

Before we begin, we would like to talk about two paradigms:

**Projects** group Android/iOS apps, Websites and all channels leveraged 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, phone number, etc. and email, SMS, etc. 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](https://doc.batch.com/developer/sdk/android/profile-data/custom-user-id) and add [Profile Attributes](https://doc.batch.com/developer/sdk/android/profile-data/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 [events](https://doc.batch.com/developer/sdk/android/profile-data/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, SMS etc. 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:

```bash
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 documentation pages, by clicking on "Test it"

#### Rate Limiting

To ensure fair usage and platform stability, all CEP API endpoints are subject to rate limiting.

**Unless specified otherwise**, APIs are subject to a rate limit of **1 request per second per project key**.

Some APIs like **Profile update** and **Edit catalog items** have custom rate limits. In those cases, the limits are documented both on the root page of this API's documentation and on their specific endpoints.

If either threshold is exceeded, the API will respond with an HTTP `429 Too Many Requests` error.\
**You are expected to handle those responses appropriately.** When that happens, slow down your requests or reduce the batch size (when applicable) to comply with the limit.

#### 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 `Authorization` 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

#### OpenAPI Spec

The OpenAPI Spec [can be downloaded here](https://openapi.gitbook.com/o/yV0lmz43uUZMgWmM3297/spec/batch-api.yaml).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.batch.com/developer/api/cep.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.