# 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](https://begenuin.com/developers/get-started/any-business/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](https://begenuin.com/developers/developer-resources/api/generate-access-token-using-authentication-api) 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](https://begenuin.com/developers/developer-resources/api/post-and-share-a-video-within-a-group-using-the-post-video-api), 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

```bash title="cURL"
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 title="Response"
{
  "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](https://begenuin.com/developers/developer-resources/api/post-and-share-a-video-within-a-group-using-the-post-video-api) and [Update a group and its members](https://begenuin.com/developers/developer-resources/api/add-or-manage-group-members-collaborators-using-api) 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.

## See also

- [Post a video to a group](https://begenuin.com/developers/developer-resources/api/post-and-share-a-video-within-a-group-using-the-post-video-api)
- [Update a group and its members](https://begenuin.com/developers/developer-resources/api/add-or-manage-group-members-collaborators-using-api)
- [Create a community](https://begenuin.com/developers/developer-resources/api/create-a-community-programmatically-using-community-api)
- [Generate an access token](https://begenuin.com/developers/developer-resources/api/generate-access-token-using-authentication-api)
- [Handle API errors](https://begenuin.com/developers/developer-resources/api/handle-api-errors)