External group segment

Partner's external group's segment

External Group Segment Management

Overview

This document outlines how to manage Group Segments within an External Group. Group Segments can be managed individually or in bulk, and users may belong to multiple segments simultaneously.

The system supports dynamic assignment and removal of users from segments via API.

---

Key Concepts

• External Group: Parent container for segmentation (1 per AUTH-TOKEN)
• Group Segment: Child entity representing a segment within an External Group
• Recipients: Users assigned to a segment, identified by phone_number and/or email

---

Capabilities

• Create one or multiple Group Segments
• Assign users to segments at creation (initial only)
• Dynamically add/remove users from segments
• Retrieve segment membership
• Delete segments

---

Create Group Segments

Before managing segment membership, you must first create one or more Group Segments.

Endpoint

POST /general/v1/external_group_segments

API Reference

Request Body (Bulk Creation)

JSON

{
  "group_segments": [
    {
      "name": "Gold"
    },
    {
      "name": "Silver"
    }
  ]
}

Create Segments with Initial Recipients

⚠️

Recipients can only be included at creation time. Future updates must use the PUT endpoint.

JSON

{
  "group_segments": [
    {
      "name": "Cancelled",
      "recipients": {
        "phone_numbers": [3056315955],
        "email": ["[email protected]"]
      }
    }
  ]
}

Recipient Identifiers

Each recipient must include at least one of the following:

• phone_numbers
• email

---

Retrieve a Group Segment

Fetch a specific Group Segment and its associated recipients.

Endpoint

GET /general/v1/external_group_segments/{id}

API Reference

Similarly, you can retrieve Group Segments

GET /general/v1/external_group_segments/

---

Update Group Segment Recipients

Dynamically manage users within a segment by adding or removing recipients.

Endpoint

PUT /general/v1/external_group_segments/{id}

Request Body

JSON

{
  "group_segment": {
    "add_recipients": {
      "phone_numbers": [
        7144878089,
        5626312791
      ],
      "email": [
        "[email protected]",
        "[email protected]"
      ]
    },
    "remove_recipients": {
      "phone_numbers": [],
      "email": []
    }
  }
}

Behavior

• add_recipients: Adds users to the segment
• remove_recipients: Removes users from the segment
• This method only manages segment membership for existing users. It cannot be used to create new users.

---

Delete a Group Segment

Remove an entire Group Segment from the External Group.

Endpoint

DELETE /general/v1/external_group_segments/{id}

Behavior

• Permanently deletes the segment
• Removes all associated recipient mappings

---

Summary

Operation	Method	Endpoint
Create Segments	POST	/external_group_segments
Retrieve Segment	GET	/external_group_segments/{id}
Update Recipients	PUT	/external_group_segments/{id}
Delete Segment	DELETE	/external_group_segments/{id}

---

Notes

• Group Segments support bulk operations at creation.
• Recipients can only be assigned during creation OR via the update endpoint.
• Segment membership is dynamic and many-to-many.