> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Profile Status

The Profile Status API attaches and removes [statuses](/concepts/profiles/tags-and-statuses) on customer profiles in batch. Use it for bulk assignment and integration work, where you are setting statuses across many profiles at once.

<Info>
  This group manages the link between a profile and a status. To create or configure the status definitions themselves, use the [Status](/api-reference/status/overview) endpoints.
</Info>

## Adding statuses is additive

`POST /v3/profile/status/batch.json` adds the handles you send and keeps the statuses each profile already holds. The endpoint merges your handles with the profile's existing statuses before saving, so existing statuses are preserved.

This is the correct endpoint for adding a status to many profiles without disturbing their other statuses.

<Warning>
  Other write paths replace the entire status set. A `PUT` to [the profile endpoint](/api-reference/profile/edit-profile) with a `statuses` array, and the profile import, both detach any status not present in the payload. To add a status while keeping existing ones, use the batch endpoint here, not those.
</Warning>

## Request shape

Send one entry per profile. Each entry needs the `profile_id` and the handles to add:

```json theme={null}
{
  "profiles": [
    { "profile_id": "123", "statuses": ["vip"] },
    { "profile_id": "456", "statuses": ["vip", "media"] }
  ]
}
```

The request is queued and returns `202` with a `batch_id`. Poll [the batch](/api-reference/batch/read-batch) with that id to track progress.

## Handle validation

Handles are matched against existing status definitions. A handle that does not match a definition is ignored without raising an error, so a typo silently does nothing. Confirm the handle exists with [Browse statuses](/api-reference/status/browse-statuses) before sending.

## Related

* [Tags and statuses](/concepts/profiles/tags-and-statuses)
* [Statuses (dev guide)](/dev-guides/profiles/statuses)
* [Status API](/api-reference/status/overview)