> ## 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.

# Statuses

> Adding statuses to profiles without removing existing ones, including bulk assignment by email.

A **status** is a named label that defines a profile's relationship with the brand, such as `vip`, `staff`, or `influencer`. For what statuses are and how they affect incentives, see [Tags and statuses](/concepts/profiles/tags-and-statuses). This guide covers how to assign them through the API.

## Adding a status is not the same as replacing them

A profile can hold several statuses at once. The write path you choose decides whether you add to that set or overwrite it.

| Write path                                      | Behaviour                                                       |
| ----------------------------------------------- | --------------------------------------------------------------- |
| `POST /v3/profile/status/batch.json`            | Adds the handles you send and keeps existing statuses           |
| `PUT /v3/profiles/{id}` with a `statuses` array | Replaces the whole set, detaching any status not in the payload |
| Profile import with a status column             | Replaces the whole set, detaching any status not in the payload |

<Warning>
  To add a status while keeping the ones a profile already holds, use the batch endpoint below. Do not use the profile `PUT` or the import for this: they remove every status that is not in your payload, so sending a single new handle wipes the rest.
</Warning>

## Add statuses without removing existing ones

`POST /v3/profile/status/batch.json` is additive. It merges the handles you send with the statuses each profile already holds, so you only need to send the new handle:

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/profile/status/batch.json \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "profiles": [
      { "profile_id": "123", "statuses": ["vip"] },
      { "profile_id": "456", "statuses": ["vip", "media"] }
    ]
  }'
```

The token needs the `update-profiles` scope. The request is queued and returns `202` with a `batch_id`:

```json theme={null}
{ "data": { "message": "Queued for processing.", "batch_id": "..." } }
```

Poll the batch to confirm it finished:

```shell theme={null}
GET /api/v3/batches/{batch_id}
```

<Note>
  Status handles are validated against existing status definitions. A handle that does not match a definition is ignored without an error, so a typo silently does nothing. Confirm the handle first with [Browse statuses](/api-reference/status/browse-statuses).
</Note>

## Bulk assign a status from a list of emails

The batch endpoint takes `profile_id`, not email, so resolve each email to a profile id first. The full flow:

<Steps>
  <Step title="Validate the status handle">
    Call [Browse statuses](/api-reference/status/browse-statuses) once and confirm the handle you intend to assign exists. Unknown handles are dropped silently, so this step prevents a run that appears to succeed but changes nothing.
  </Step>

  <Step title="Resolve each email to a profile id">
    Filter the browse profiles endpoint by email. See [Filtering profiles](/dev-guides/profiles/filtering-profiles).

    ```shell theme={null}
    GET /api/v3/profiles?filter[email]=jane@example.com
    ```

    Read the id from the first match. Handle the cases where no profile matches, or more than one does, by logging them and skipping rather than guessing.
  </Step>

  <Step title="Send the batch">
    Build one entry per resolved profile and `POST` to `/v3/profile/status/batch.json`. Send the new handle only; existing statuses are preserved server-side. Split large jobs into chunks of a few hundred profiles per request.
  </Step>

  <Step title="Confirm">
    Poll each returned `batch_id`, then spot-check a few profiles with `GET /api/v3/profiles/{id}?include=statuses` to confirm the new handle is present alongside their existing statuses.
  </Step>
</Steps>

Because the endpoint is additive and de-duplicates handles, re-running the job is safe: assigning a status a profile already has is a no-op.

## Remove a status

To remove statuses in bulk without touching the rest, use `DELETE /v3/profile/status/batch.json` with the same request shape. It detaches only the handles you send.

## Related

* [Tags and statuses](/concepts/profiles/tags-and-statuses)
* [Profile Status API](/api-reference/profile-status/overview)
* [Status API](/api-reference/status/overview)
* [Filtering profiles](/dev-guides/profiles/filtering-profiles)
* [Tags](/dev-guides/profiles/tags)