---
title: "Create a group"
description: "Creates a keyword group. `name` must be unique in the workspace. `externalId` is optional and also unique. It is your own id, such as a client id, so you can find the group without storing ours. `context` is optional. It is a company description for this group, which the classifier reads instead of the workspace profile for the group's keywords. Then send the group's id as `groupId` when you create a keyword."
canonical: https://docs.rumoro.dev/api/groups/create-group
markdown: https://docs.rumoro.dev/api/groups/create-group.mdx
---

# Create a group

`POST /v1/groups`

Creates a keyword group. `name` must be unique in the workspace. `externalId` is optional and also unique. It is your own id, such as a client id, so you can find the group without storing ours. `context` is optional. It is a company description for this group, which the classifier reads instead of the workspace profile for the group's keywords. Then send the group's id as `groupId` when you create a keyword.

## Body

| Field | Required | Description |
| --- | --- | --- |
| `name` | yes | The group's name, such as a client, campaign or product. Must be unique in the workspace. |
| `externalId` |  | An id from your own system, such as a client id. Must be unique in the workspace. Find the group with GET /v1/groups?externalId=. |
| `context` |  | Up to 4000 characters the classifier treats as "the company" for this group's keywords. It fully replaces the workspace profile, including its relevance guidelines and competitors. Describe the business, what it sells and to whom, what it is not, and any rule for this group, such as "ignore job posts". With one group per client, use the client's description. Null means the workspace profile is used. |

## Responses

| Status | Meaning |
| --- | --- |
| 201 | The group that was created |
| 401 | The API key is missing or not valid |
| 409 | This name or externalId is already used by a group (duplicate_group) |

The [OpenAPI document](https://api.rumoro.dev/v1/openapi.json) has every schema. Rules shared by all endpoints are in [Conventions](https://docs.rumoro.dev/conventions.mdx).