---
title: "Replace"
method: POST
path: "/audiences/replace"
tags: ["Audiences"]
---

# Replace

`POST /audiences/replace`

Replace all audience users. It removes all previously added users and adds the given ones.

## Headers

- `X-Batch-Project` string, required

## Request body

- object
  - `name` string, required — The name of the existing audience you want this operation to be applied to.
  - `ids` object[], required — An array of objects describing ids to be added to the audience. If empty, all users will be removed from the audience.
    - `id` string, required — The ID that will be added to the audience.
    - `attributes` object — Only accepted for `add` action. <br/>An object containing attributes to be attached to the id. They can then be used in [message personalization](https://doc.batch.com/guides/message-personalization/advanced/#custom-audience-data). <br/>Supports up to 15 elements. See the Custom Data API documentation for more info on attribute names and values.

## Response `202`

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and an indexing token. <br/>Once you get your indexing token, you can use it to check the indexing state with the view action.

- object
  - `indexing_token` string

## Other responses

- `400` — The request is malformed
- `401` — The Rest API Key is not valid for this project
- `429` — Too Many Requests
- `500` — Unexpected error
- `503` — Batch's services are under maintenance. Please try again later

---

[API](https://skmtc.net/batch/apis/batch-rest-api.md) · [All operations](https://skmtc.net/batch/apis/batch-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/batch/batch-rest-api/revisions/ec696334ff35/schema)