Create a group in a community

Create a group inside a community, with its visibility and posting rules, first members, and an optional opening video.

A group is where videos are posted and discussed; every video belongs to a group, and every group to a community. This endpoint creates one the same way Manage > Groups > Create does in Brand Control Center. Use it to open a group per product, episode, or campaign from your own systems. Create communities and groups explains how the two fit together.

The account behind your access token owns the group, so it has to be a member of the community. Your brand's owner account is a moderator of every community created under the brand. See Generate an access token for the token.

Endpoint

POST /api/thirdparty/group/create

Environment	Base URL
Production	https://api.begenuin.com
QA	https://api.qa.begenuin.com

Send the token as a bearer token in the Authorization header, and the fields as a JSON body with the Content-Type: application/json header.

Parameters

Parameter	Type	Required	Description
type	integer	Required	4. Groups are conversation type 4.
community_id	string	Required	UUID of the community. It has to belong to your brand, or to a brand in your network.
group	object	Required	The group itself. See Group object.
actions	array	Required	Who can see and who can post in the group. See Actions.
recorded_video	object	Optional	An opening video, uploaded first. See Recorded video.
chat_id	string	Optional	A UUID to use as the group's id, when your system assigns ids.
template_id	integer	Optional	A group template. Only the community's leader can send it; others get 400.
is_welcome_loop	boolean	Optional	Makes this the community's welcome group. Leader or moderator only, one per community, and actions has to equal the welcome-group defaults.
is_ai_generated	boolean	Optional	Marks the group as AI-generated. Default false.
platform	string	Optional	mobile or web, used to validate link-out URLs.
language	string	Optional	Language code, such as en.
location	object	Optional	{"latitude": <-90 to 90>, "longitude": <-180 to 180>}.

settings is accepted but ignored: every group is created with discoverable set to true.

Group object

Field	Type	Required	Description
name	string	Required	The group's name.
description	string	Required	The description. Hashtags are kept as written.
tags	string	Required	Comma-separated discovery tags. Send "" for none.
dp	string	Optional	File name of the group image, uploaded to Genuin's media storage first.
topics	array of integers	Optional	Topic ids to classify the group.
members	array	Optional	First members, each {"user_id": "<uuidv4>"} or {"phone_number": "<10 to 15 digits>"}, never both. Your own account is skipped. In a private community, every member has to be a community member already.

Actions

actions has exactly two entries: who can see the group and who can post in it. The ids differ by community type.

Community type	action_id	Setting	access_type_id	Option
Public	3	Who can see this group	5	Everyone, including people without an account
Public	3	Who can see this group	6	Group members only
Public	5	Who can post in this group	9	All community members
Public	5	Who can post in this group	10	Group members only
Private	4	Who can see this group	7	All community members
Private	4	Who can see this group	8	Group members only
Private	6	Who can post in this group	11	All community members
Private	6	Who can post in this group	12	Invite-only

A group that only its members can see can't let all community members post: 6 with 9, and 8 with 11, are rejected. A missing action, an extra one, or an option that doesn't belong to its action returns 412 with code 5166.

Recorded video

recorded_video attaches an opening post. Upload the video and its thumbnail first, as described in Post a video to a group, then pass:

Field	Type	Required	Description
video_name	string	Required	File name you uploaded under temp_video/. Each name can be posted once.
thumbnail_name	string	Required	File name you uploaded under uploads/thumbnails/.
size	string	Required	File size, such as "5MB".
duration	integer	Required	Length in seconds.
aspect_ratio	string	Required	Such as "9:16".
resolution	string	Required	Such as "1080x1920".
meta_data	object	Required	Free-form, such as {"topic": "Open discussion"}. Send {} for none.
description_text	string	Optional	Caption, up to 2,000 UTF-16 code units. Requires description_data.
description_data	string	Required with description_text	JSON string of the caption split into text and mentions, such as ["Hello ", {"user_id": "<uuid>"}].
link	string	Optional	A link shown with the video. Can't be combined with linkouts.
linkouts	array	Optional	Link-out cards; see Post a video to a group.
message_id	string	Optional	A UUIDv4 to use as the post's id.
video_path, thumbnail_path, is_ai_generated_video, is_ai_generated_thumbnail	string, boolean	Optional	For media produced by Genuin's generation flow: the source folders in the generation bucket, and the flags that copy them.

Returns

Returns 200 OK with the group card: its id, share URL, settings, the group object with its members, the opening video when you sent one, and the community it belongs to. The group is live immediately.

Request

cURL

bash

curl -X POST https://api.begenuin.com/api/thirdparty/group/create \
  -H "Authorization: Bearer {{GN_ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": 4,
    "community_id": "{{COMMUNITY_ID}}",
    "group": {
      "name": "Race recaps",
      "description": "Post your finish-line video and tell us how it went #recap",
      "tags": "recap,races",
      "members": [{ "user_id": "{{USER_ID}}" }]
    },
    "actions": [
      { "action_id": 3, "access_type_id": 5 },
      { "action_id": 5, "access_type_id": 9 }
    ]
  }'

Response

json

{
  "code": 200,
  "message": "Group has been created successfully.",
  "data": {
    "chat_id": "456e7890-b12c-4c23-89ef-126314214567",
    "type": 4,
    "settings": { "discoverable": true },
    "share_url": "https://community.example.com/community/trail-runners/race-recaps",
    "is_welcome_loop": false,
    "group": {
      "group_id": "f67c89d0-9abc-4abc-bdef-56789abcf456",
      "group_name": "Race recaps",
      "group_description": "Post your finish-line video and tell us how it went #recap",
      "color_code": "#A4E6DA",
      "text_color_code": "#49CDB5",
      "dp": null,
      "dp_s": "",
      "dp_m": "",
      "dp_l": "",
      "no_of_members": 1,
      "members": [
        {
          "member_id": "0bf977ed-4887-4056-a8f4-1f0de71101f1",
          "name": "Example Brand",
          "username": "examplebrand",
          "is_avatar": false,
          "is_brand_system_user": true,
          "status": 1,
          "role": 1,
          "profile_image": "https://media.begenuin.com/uploads/profile_images/1706610191569_Vector.png",
          "profile_image_s": "https://media.begenuin.com/uploads/profile_images/s/1706610191569_Vector.png",
          "profile_image_m": "https://media.begenuin.com/uploads/profile_images/m/1706610191569_Vector.png",
          "profile_image_l": "https://media.begenuin.com/uploads/profile_images/l/1706610191569_Vector.png",
          "brand": { "brand_id": 1429, "brand_slug": "example-brand", "brand_user_logo": null }
        }
      ]
    },
    "latest_messages": [],
    "latest_message_at": 1760543999000,
    "unread_message_count": 0,
    "actions": [
      { "action_id": 3, "access_type_id": 5, "access_to_everyone": true, "roles": [] },
      { "action_id": 5, "access_type_id": 9, "access_to_everyone": false, "roles": [2, 3, 1] }
    ],
    "brand_id": 1429,
    "no_of_views": 0,
    "no_of_videos": 0,
    "community": {
      "community_id": "0a2be302-04af-4642-a436-1612554e48a6",
      "handle": "trail-runners",
      "name": "Trail Runners",
      "description": "Weekly routes, gear talk, and race recaps #trailrunning",
      "color_code": "#A4E6DA",
      "text_color_code": "#49CDB5",
      "dp": null,
      "dp_s": null,
      "dp_m": null,
      "dp_l": null,
      "share_url": "https://community.example.com/community/trail-runners"
    }
  }
}

chat_id is the group's id; Post a video to a group and Update a group and its members take it. group.group_id identifies the group's profile record and isn't used by the other endpoints. In group.members, role is 1 for the owner, 2 for an admin, and 3 for a member. With a recorded_video, latest_messages holds the opening post with its message_id and share_url.

Errors

Every error response carries an HTTP status, a string code, a message, and a data object. Match on code.

HTTP status	code	Cause	Fix
400 Bad Request	none	A field failed validation, or a non-leader sent template_id. The body is {"data": {}} with no code or message.	Check the Parameters tables.
401 Unauthorized	5159	The token's account isn't a member of the community. Message: Invalid Use of API.	Add the account to the community first, or use the brand owner's token.
403 Forbidden	5230	The community's "who can create groups" setting excludes the token's account. Message: XXXX-[Access Denied]..	Have a leader or moderator create the group, or change the setting in Brand Control Center.
403 Forbidden	5243	The community belongs to a brand outside your network.	Use a community under your brand.
409 Conflict	5156	recorded_video.video_name was already posted. data carries the existing video_id.	Upload the video under a new file name.
409 Conflict	5167	A group with the same share string already exists.	Omit share_string.
412 Precondition Failed	5166	actions doesn't match the community type, a member of a private community's group isn't a community member, the welcome-group rules aren't met, or the community lookup failed.	Send the two actions from the Actions table, and check the member ids.
412 Precondition Failed	5227	The community already has a welcome group.	Omit is_welcome_loop.
404 Not Found	5235	Link-out validation needs the brand, and it isn't active.	Contact the Genuin team.
400 Bad Request	1099	The server couldn't process the request.	Retry once. If it persists, contact the Genuin team with the request timestamp.

Limitations

Always discoverable: settings.discoverable is forced to true on creation, and the update endpoint only accepts true.
Templates for leaders only: template_id needs the community leader's account.
Rate limit: There's no rate limit on this endpoint.