Skip to main content
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. 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 pathBehaviour
POST /v3/profile/status/batch.jsonAdds the handles you send and keeps existing statuses
PUT /v3/profiles/{id} with a statuses arrayReplaces the whole set, detaching any status not in the payload
Profile import with a status columnReplaces the whole set, detaching any status not in the payload
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.

​
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: 
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: 
{ "data": { "message": "Queued for processing.", "batch_id": "..." } }
Poll the batch to confirm it finished: 
GET /api/v3/batches/{batch_id}
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.

​
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:
1

Validate the status handle

Call 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.
2

Resolve each email to a profile id

Filter the browse profiles endpoint by email. See Filtering profiles.
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.
3

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

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