---
title: "Create or retrieve a group by name"
method: POST
path: "/v1/projects/{project_id}/groups"
tags: ["Group"]
---

# Create or retrieve a group by name

`POST /v1/projects/{project_id}/groups`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/groups`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Retrieves or creates a group by name. If a group with that name does not exist, a new normal group will be created, initially empty. (To create a dynamic group, or to create a group with additional options such as `solution_id`, use project.createGroup.)

## Path parameters

- `project_id` string, required

## Request body

- object
  - `name` string, required: Name of the group

## Response `200`

Successful response

- Group: Represents a group used to organize contacts within Telerivet.
  - `id` string: ID of the group
  - `name` string: Name of the group
  - `dynamic` boolean: Whether this is a dynamic or normal group
  - `filters` object, nullable: Key-value pairs of conditions that contacts must match to be members of a dynamic group. To filter by a custom variable, precede the variable name with 'vars.' (conditions on custom variables may also be provided as a nested object under a `vars` key, e.g. `{"vars": {"city": "Manila"}}`); other supported keys are `id`, `name`, `phone_number`, `time_created`, `time_updated`, `incoming_message_count`, `outgoing_message_count`, `last_incoming_message_time`, `last_outgoing_message_time`, `conversation_status`, `send_blocked`, `group` (ID of a normal group whose members should be included), `not_group` (ID of a normal group whose members should be excluded), and `q` (full-text search query matching contacts like the search box in the web app). Each value is either a value to match exactly, or an object with an operator such as `ne`, `prefix`, `gte`, `lt`, `exists`, or `not_exists` as the key (e.g. `{"gte": 10}`). Null if this is a normal group. Filter conditions can only be updated on dynamic groups.
  - `num_members` integer, nullable: Number of contacts in the group (null if the group is dynamic)
  - `time_created` integer: Time the group was created in Telerivet
  - `allow_sending` boolean: True if messages can be sent to this group, false otherwise.
  - `add_time_variable` string, nullable: Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable. If the project does not have a contact field with this variable name, a new date/time field will be created. This is useful as the `date_variable` of a `relative` campaign that sends messages relative to when each contact joins the group.
  - `solution_id` string, nullable: ID of the solution that this group belongs to, if any
  - `vars` object: Custom variables stored for this group. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `url` string: URL to this group in the Telerivet web app
  - `project_id` string: ID of the project this group belongs to

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)