# Add members to a community

Add existing accounts or phone numbers to a community, or approve a pending join request, from your own systems.

Use this endpoint to onboard members from a CRM, a signup flow, or a campaign, the way **Manage** > **Users** does in Brand Control Center. Members gain access to the community's groups and videos as soon as the call returns. The account behind your access token does the adding, so it has to be an active 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/community/add_users`

| 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 |
| --- | --- | --- | --- |
| communities | array of strings | Required | UUIDs of the communities to add to. Duplicates are removed. |
| users | array | Required | Who to add, each {"user_id": "<uuid>"} or {"phone_number": "<digits>"}. See Identify users. |
| invite_members | boolean | Optional | true adds the users as members on your behalf. This is the mode for server integrations. |
| join_request_approved | boolean | Optional | true approves one pending join request to one private community: exactly one community and one user_id. |
| onboarding_communities | boolean | Optional | App onboarding mode: the token's own account joins public communities and is marked as onboarded. |

Send at most one of the three flags. With none of them, the call runs in single-tap mode: the token's own account joins one public community, and nobody else can be added.

Add many users to one community, or one user to many communities. Many users to many communities returns `412`.

### Identify users

- `user_id` is the UUID of an existing Genuin account. Deleted accounts are skipped.
- `phone_number` is digits only with the country code first and no plus sign, such as `14155552671`. A number without an account gets a pending account with that number; the person takes it over when they sign up with the same number. Pending members are added with an inactive status and become active on signup.

Accounts that are already active members are left as they are and don't appear in `members_added`. A member who left earlier is reinstated.

## Returns

With `invite_members`, returns `200 OK` and the member objects that were added. Each new member gets a "you were invited" notification, and the community's member count updates.

With `join_request_approved`, returns `200 OK` with empty `data`, and the member gets an approval notification.

With `onboarding_communities` or no flag, returns `200 OK` with `is_loop_creation_allowed`, which says whether the joined community lets this member create groups, and `welcome_loop_id` when the community has a welcome group.

## Request

```bash title="cURL"
curl -X POST https://api.begenuin.com/api/thirdparty/community/add_users \
  -H "Authorization: Bearer {{GN_ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "communities": ["{{COMMUNITY_ID}}"],
    "invite_members": true,
    "users": [
      { "user_id": "{{USER_ID}}" },
      { "phone_number": "14155552671" }
    ]
  }'
```

## Response

```json title="Response"
{
  "code": 200,
  "message": "XXXX-[Members Added]",
  "data": {
    "members_added": [
      {
        "member_id": "c2fd91a1-faf8-48a8-9b3e-b2248c8acf21",
        "name": "Avery Chen",
        "bio": null,
        "nickname": "averyc",
        "phone": "14155550111",
        "is_brand_system_user": false,
        "is_avatar": true,
        "profile_image": "alien",
        "profile_image_s": "",
        "profile_image_m": "",
        "profile_image_l": ""
      },
      {
        "member_id": "bd7608b7-5c0b-4fcc-9799-5944de1b6f5d",
        "name": null,
        "bio": null,
        "nickname": null,
        "phone": "14155552671",
        "is_brand_system_user": false,
        "is_avatar": true,
        "profile_image": "smiling_face_with_horns",
        "profile_image_s": "",
        "profile_image_m": "",
        "profile_image_l": ""
      }
    ]
  }
}
```

`member_id` is the account's UUID; use it for later calls such as [Add moderators to a community](https://begenuin.com/developers/developer-resources/api/assign-moderators-to-community-using-api). A pending account created from a phone number has `null` for `name` and `nickname` and an avatar name in `profile_image` until the person signs up. An account with an uploaded photo has CDN URLs in `profile_image` and the `_s`, `_m`, and `_l` sizes.

## 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 |
| --- | --- | --- | --- |
| 412 Precondition Failed | 5166 | The request breaks a rule: a missing or non-UUID community, an empty users list, more than one flag, many users to many communities, a join_request_approved call without exactly one private community and one user_id, a single-tap call that adds someone other than the token's account, or the token's account isn't an active member (for a private community, leader or moderator) of every listed community. Message: XXXX-[Invalid Use of API]. | Send one community or one user, one flag, and make sure your account is a member of the community. |
| 404 Not Found | 5218 | The community doesn't exist or is deleted. Message: The community you are looking for is no longer available. | Check the UUID. |
| 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

- **One-to-many only**: One community with many users, or one user with many communities, per call.
- **No roles**: Everyone is added as a member. Use [Add moderators to a community](https://begenuin.com/developers/developer-resources/api/assign-moderators-to-community-using-api) for admins.
- **No removal**: There's no third-party endpoint to remove a member from a community. Remove members in Brand Control Center under **Manage** > **Users**.
- **Rate limit**: There's no rate limit on this endpoint.

## See also

- [Create a community](https://begenuin.com/developers/developer-resources/api/create-a-community-programmatically-using-community-api)
- [Add moderators to a community](https://begenuin.com/developers/developer-resources/api/assign-moderators-to-community-using-api)
- [Update a group and its members](https://begenuin.com/developers/developer-resources/api/add-or-manage-group-members-collaborators-using-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)