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 for the token.

Endpoint

POST /api/thirdparty/community/add_users

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

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

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

{
  "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. 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.

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 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
• Add moderators to a community
• Update a group and its members
• Generate an access token
• Handle API errors