# Account groups

Save named sets of accounts, such as all of a brand's channels, and reuse them when you post or report.

An account group is a saved, named list of account ids, for example "Acme launch channels" or "Spain stores". Groups do not change how accounts behave. They save you from rebuilding the same list of accounts every time someone posts, filters a report or sets up an automation.

Groups can mix accounts from different profiles and platforms. Removing a group never touches the accounts in it.

## Create a group

```bash cURL
curl -X POST "https://api.pozy.ai/v1/account-groups" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme launch channels",
    "accountIds": ["6651d3a7b2c9e4f1a0b8c7d6", "6651d3a7b2c9e4f1a0b8c7d7", "6651d3a7b2c9e4f1a0b8c7d8"]
  }'
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/account-groups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme launch channels",
    accountIds: ["6651d3a7b2c9e4f1a0b8c7d6", "6651d3a7b2c9e4f1a0b8c7d7", "6651d3a7b2c9e4f1a0b8c7d8"],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.group._id);
```
```python Python
resp = requests.post(
    "https://api.pozy.ai/v1/account-groups",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "name": "Acme launch channels",
        "accountIds": ["6651d3a7b2c9e4f1a0b8c7d6", "6651d3a7b2c9e4f1a0b8c7d7", "6651d3a7b2c9e4f1a0b8c7d8"],
    },
    timeout=30,
)
group_id = resp.json()["group"]["_id"]
```

```json
{
  "message": "Account group created",
  "group": {
    "_id": "6652a0c4d1e8f3b7a9c2e5d1",
    "name": "Acme launch channels",
    "accountIds": ["6651d3a7b2c9e4f1a0b8c7d6", "6651d3a7b2c9e4f1a0b8c7d7", "6651d3a7b2c9e4f1a0b8c7d8"]
  }
}
```

Group names must be unique. Every account id must belong to this workspace, and your key must be able to reach its profile.

## List, rename and change

| Job | Call |
| --- | --- |
| List groups | `GET /v1/account-groups` |
| Rename, or replace the account list | `PUT /v1/account-groups/{groupId}` with `name`, `accountIds` or both |
| Delete a group | `DELETE /v1/account-groups/{groupId}` |

`PUT` replaces `accountIds` as a whole. To add one account, send the current list plus the new id.

## Post to a group

A post targets accounts, not groups, so expand the group into `platforms` when you create the post. Look up each account's platform once with `GET /v1/accounts`:

```ts
const groupsRes = await fetch("https://api.pozy.ai/v1/account-groups", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const groups = await groupsRes.json();
if (!groupsRes.ok) throw new Error(groups.error);
const group = groups.groups.find((g) => g.name === "Acme launch channels")!;

const accountsRes = await fetch("https://api.pozy.ai/v1/accounts", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const accounts = await accountsRes.json();
if (!accountsRes.ok) throw new Error(accounts.error);
const byId = new Map(accounts.accounts.map((a) => [a._id, a]));

const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "We open in Madrid on Saturday. First coffee is on us.",
    platforms: group.accountIds
      .filter((id) => byId.has(id))
      .map((id) => ({ platform: byId.get(id)!.platform, accountId: id })),
    publishNow: true,
  }),
});
if (!res.ok) throw new Error((await res.json()).error);
```

Filter out ids that no longer exist. A group keeps the ids you saved, even after one of those accounts is disconnected.

## Profile-scoped keys

A key scoped to some profiles only sees groups whose accounts all live in those profiles. It cannot create or change a group that includes an account outside its scope: that returns `403 profile_out_of_scope`.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/account-groups`](https://pozy.ai/docs/api/listAccountGroups) | List groups |
| [`POST /v1/account-groups`](https://pozy.ai/docs/api/createAccountGroup) | Create group |
| [`PUT /v1/account-groups/{groupId}`](https://pozy.ai/docs/api/updateAccountGroup) | Update group |
| [`DELETE /v1/account-groups/{groupId}`](https://pozy.ai/docs/api/deleteAccountGroup) | Delete group |