---
title: "Create Group"
method: POST
path: "/api/v1/groups"
tags: ["Groups"]
---

# Create Group

`POST /api/v1/groups`

Creates a new group with associated websites. Requires a global API key. **Partner integrations** may include an `external_id` to map their own identifier onto the new Athena group.

## Request body

- CreateGroupRequest — Request body for creating a new group
  - `name` string, required — Name of the group.
  - `website_ids` string[], required — List of website IDs to include in the group. All websites must belong to your organization.
  - `billing_enabled` boolean — Whether to enable billing for this group
  - `external_id` string — **Partner-only.** An identifier from your own system to map to this Athena group. Accepted only when authenticating with an API key for an organization flagged as a partner. Sending this field as a direct customer returns `403 Forbidden`. Must be unique per resource type within your organization — duplicates return `409` with the existing resource in the payload.

## Response `201`

Group created successfully

- object
  - `group` CreatedGroup, required — A newly created group resource
    - `id` string, uuid, required — Unique identifier for the group
    - `name` string, required — Name of the group
    - `orgId` string, uuid, required — The organization ID the group belongs to
    - `billingEnabled` boolean, required — Whether billing is enabled for this group
    - `websiteIds` string[], required — List of website IDs associated with this group
    - `createdAt` string, date-time, required — Timestamp when the group was created (UTC)
    - `externalId` string, nullable — **Partner-only.** Echoes the `external_id` from the create request if provided, or `null` if the partner did not supply one. Only present on responses to partner API keys — direct-customer responses omit the field.
  - `billingEntityCreated` boolean — Present only when billing_enabled was requested: whether the billing entity exists after provisioning. When false, entity creation failed even after a retry, and setting group credits fails with a 400 until billing is repaired via PATCH /api/v1/groups/{group_id} with billing_enabled: true.

## Other responses

- `400` — Bad request - Validation error or invalid website IDs
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Requires a global API key, or (partner-only field) the key lacks partner identity for an `external_id`.
- `409` — Conflict - (partners only) the supplied `external_id` is already mapped to another group.
- `500` — Internal server error

---

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