How do you create a community programmatically using the Create Community API?

Who is this for and why it matters

Use this API when you want to automate community creation within your Community Media Network instead of manually setting it up via the Brand Control Center.

This matters because:

It enables scalable community creation across products, campaigns, or user flows
It allows real-time community setup based on user actions or integrations
It reduces manual dependency and accelerates onboarding

If you're building integrations, onboarding flows, or dynamic community experiences, this API is essential.

What does the Create Community API do?

The Create Community API allows you to:

Programmatically create a new community
Assign categories (existing or new)
Configure branding (DP, banner, colors)
Add users to the community
Enable AI-assisted generation (DP/banner)

It’s the foundation for automating community infrastructure within Genuin.

API Details

URL: /api/thirdparty/community/create
Method: POST
Authentication Required: Yes (Bearer Token)
Mandatory Fields: handle, name, type, actions

Before you begin

1. Authenticate your request

You must generate a gn-access-token using the Authentication API.

Pass this token as a Bearer Token in the request header:

Authorization: Bearer <gn-access-token>

Without this, the API will reject your request.

Request Structure

Request Body

{
  "handle": "genuin-community",
  "name": "Genuin Community",
  "description": "some community description #genuinCommunity #genuinAmdCommunity",
  "tags": "genuinCommunity,genuinAmdCommunity",
  "dp": "1.png",
  "categories": {
    "existing": [1, 2],
    "new": ["abc", "aAa", "xYZ"]
  },
  "is_ai_generated": false,
  "is_ai_generated_dp": true,
  "is_ai_generated_banner": true,
  "banner": "1.png",
  "users": [
    {
      "user_id": "b12f13af-ef5a-4906-b0a0-2995e106200d"
    }
  ]
}

Field-level understanding

handle - Unique identifier for the community (must be unique)
name - Display name of the community
description - Community description with hashtags
tags - Comma-separated tags for discovery
dp - Display picture file reference
banner - Banner image file reference
categories
- existing - Use predefined category IDs
- new - Create new categories dynamically
is_ai_generated - Whether community is AI-generated
is_ai_generated_dp/banner - Enable AI-generated visuals
users - Add initial members to the community

What happens on success?

Success Condition

If all inputs are valid and processed correctly:

Community is created successfully
Metadata and assets are returned

Response Code 200 OK

Response Body

{
  "code": 200,
  "message": "XXXX-[Community has been created successfully.]",
  "data": {
    "community_id": "0a2be302-04af-4642-a436-1612554e48a6",
    "share_url": "https://community.dhruvpatel.com/community/dqwd-w5oa",
    "dp": "https://media.qa.begenuin.com/uploads/profile_images/community/eeqfwee12.png",
    "banner": "https://media.qa.begenuin.com/uploads/community/banner/dqwdq.png",
    "color_code": "#A4E6DA",
    "text_color_code": "#49CDB5",
    "leader": {
      "member_id": "0bf977ed-4887-4056-a8f4-1f0de71101f1",
      "name": "hoo hwwoo",
      "bio": "jai hwwooo",
      "nickname": "wdqwdqwdq",
      "phone": "91333333333333",
      "is_brand_system_user": true,
      "is_avatar": false,
      "brand": {
        "brand_id": 1,
        "brand_slug": "dqwd-dqjb"
      },
      "profile_image": "https://media.qa.begenuin.com/uploads/profile_images/1706610191569_Vector.png"
    }
  }
}

Important

community_id - Unique identifier of the created community
share_url - Public link to access the community

Error Handling

1. Bad Request

Condition:

Invalid request payload
Missing or malformed data

Response Code: 400 Bad Request

Response Body: {}

2. Category Does Not Exist

Condition: Provided category IDs are invalid

Response Code: 404 Not Found

Response Body:

{
  "code": "5220",
  "message": "XXXX-[community categories does not exists.]",
  "data": {}
}

3. Invalid API Usage

Condition: API usage rules are violated

Response Code: 412 Precondition Failed

Response Body:

{
  "code": "5166",
  "message": "XXXX-[Invalid Use of API]",
  "data": {}
}

4. Internal Server Error

Condition:

Duplicate community handle
Unexpected server issue

Response Code: 500 Internal Server Error

Response Body:

{
  "code": "5216",
  "message": "XXXX-[community handle already exists.]",
  "data": {}
}

Best Practices

Ensure the handle is unique to avoid conflicts
Validate category IDs before passing them
Use AI-generated assets for faster community setup when needed
Always pass a valid gn-access-token
Implement retry and error handling for production integrations

What to do next

Once the community is created:

Use the community_id for further API operations
Share the share_url with users
Start ingesting content, adding members, or monetizing the community