Overview

The Update Segment API allows you to manage user profiles in CleverTap by adding or removing users from API segments. It does not apply to segments created via the dashboard or partner segments. This API allows bulk updates to user segments, ensuring profiles stay accurate in the relevant segments based on updated behavior, preferences, or attributes.

The Update Segment API uses partial processing. If a request contains both valid and invalid entries, valid entries are processed while invalid entries are skipped. Invalid entries are logged in the Error Stream dashboard, along with Segment ID, Customer Segment ID, and User Identity.

With this API, you can:

• Update multiple user profiles simultaneously, adding or removing them from various segments.
• Refine segments based on changing user data or actions.
• Manage and maintain dynamic user segments for better targeting and engagement.
• Simplify user segmentation by using either CleverTap segment IDs, ct_segment_id, or customer-defined segment IDs, customer_segment_id.

Base URL

Here is an example base URL from the account in the India region:

https://<region>.api.clevertap.com/api/updateSegment

Region

To identify the API endpoint for your account's region, refer to Region.

Headers

For more information about API headers used while processing API requests, refer to Headers.

HTTP Method

POST

Request Parameters

The request body contains an array of bulk_profiles, where each entry consists of user profile details and segment information.

Each bulk_profiles entry updates multiple user profiles and assigns them to specified segments using either a CleverTap segment ID (ct_segment_id) or a customer-defined segment ID (customer_segment_id). Each request can include up to 100 user IDs for one or more segments and up to 100 segments.

📘

Request Payload

If both ct_segment_id and customer_segment_id are provided in the request payload, they must match. If they do not match, the corresponding entry is skipped, and the error is logged in the Error Stream dashboard. Other valid entries in the request are still being processed.

Example Request

The following is the sample request:

{
  "bulk_profiles": [
    {
      "user_profiles": [
        {
          "guid": "abcde12345",
          "identity": "[email protected]"
        },
        {
          "guid": "fghij67890",
          "identity": "[email protected]"
        }
      ],
      "segments": [
        {
          "ct_segment_id": 1234,
          "customer_segment_id": "abc123",
          "action": "ADD"
        },
        {
          "ct_segment_id": 5678,
          "action": "REMOVE"
        },
        {
          "customer_segment_id": "customer_id_123",
          "action": "ADD"
        }
      ]
    }
  ]
}

Example Response

The API returns HTTP 200 when the request is accepted, even if some entries are invalid. Valid entries are processed successfully, while invalid entries are skipped and reported in the Error Stream dashboard.

The following is the sample response:

{
  "success": true
}

Request Limit

For information on request limits for the Update Segment API, refer to API Request Limit.

Error Stream Reporting

Invalid entries in the request are logged to the Error Stream dashboard instead of causing the entire request to fail.

Each logged error includes the following fields:

You can view these errors in the Error Stream dashboard to diagnose issues with individual segment updates.

Errors

The following errors may occur while processing Update Segment API requests.

Request-Level Errors

Some errors apply to the entire request, while others are logged in the Error Stream dashboard when individual entries are invalid.

Segment Processing Errors

The following errors are logged in the Error Stream dashboard when specific request entries are invalid. These errors do not cause the entire request to fail. The affected entries are skipped while valid entries are processed.