Create Group

Endpoint

POST /v2/groups

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: users:write

The group is recorded as created by the access token’s user.

Request Body

The request body must be a JSON object with the following fields:

Required Fields

Field	Type	Description
`name`	string	Name of the new group. Must be at least 1 character

Optional Fields

Field	Type	Description
`users_ids`	array	Identifiers of the users to add as initial members. Defaults to an empty array

Request Example

curl -X POST https://platform.chamelio.ai/v2/groups \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legal",
    "users_ids": [1001, 1002]
  }'

import requests

url = "https://platform.chamelio.ai/v2/groups"
headers = {
    "Authorization": "Bearer your_access_token",
    "Content-Type": "application/json"
}
payload = {
    "name": "Legal",
    "users_ids": [1001, 1002]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch('https://platform.chamelio.ai/v2/groups', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Legal',
    users_ids: [1001, 1002]
  })
});

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK

{
  "group_id": 14,
  "name": "Legal",
  "member_user_ids": [1001, 1002],
  "created_at": "2025-06-04T10:15:00Z"
}

Response Fields

Field	Type	Description
`group_id`	integer	Unique identifier of the newly created group
`name`	string	Name of the newly created group
`member_user_ids`	array	Identifiers of the users added to the group
`created_at`	string	ISO 8601 timestamp of when the group was created

Error Responses

400 Bad Request

Returned when the request is invalid - for example, a group name that already exists or an invalid user identifier - or when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "Group with this name already exists"
}

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "detail": "Insufficient scope; this endpoint requires: users:write"
}

422 Unprocessable Entity

Returned when the request body fails validation - for example, an empty name.

{
  "detail": "Validation error"
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the group could not be created due to a server error.

{
  "detail": "Failed to create group"
}

Notes

The new group is always created in the organization the token is bound to. The users_ids you supply are returned as member_user_ids in the response. Retrieve valid user identifiers via GET /v2/users.

Use Cases

This endpoint is useful for:

Group provisioning - Programmatically create groups from an external system
Team setup - Seed a new group with its initial members in a single request
Access organization - Structure users into groups for downstream workflows

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Request Body

Required Fields

Optional Fields

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Request Body

​Required Fields

​Optional Fields

​Request Example

​Response

​Success Response

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Request Body

Required Fields

Optional Fields

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases