Update Segment

Change a segment's name, description or rules. Send only the fields you want to change.

Sending filter replaces the whole rule tree. The members are then recomputed in the background: the segment returns to status: "processing", and contact_count is null until it is "ready" again. Changing only the name or description leaves the members as they are.

Endpoint

PATCH /segments/:id

Returns: 200 OK

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Description
id	string	The segment ID

Body Parameters

Parameter	Type	Required	Description
name	string	No	Segment name. Max 100 characters.
description	string	No	Description. Max 500 characters.
filter	object	No	The new rules, replacing the current ones. See Segment Filters.

Response

The updated segment. See List Segments for the field reference.

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "name": "VIP customers (email)",
  "description": "Opened 3+ emails in the last 90 days",
  "status": "processing",
  "filter": {
    "type": "group",
    "operator": "and",
    "conditions": [
      {
        "type": "engagement_count",
        "channel": "email",
        "action": "opened",
        "operator": "greater_than_or_equal",
        "value": 3,
        "time_window": { "value": 90, "unit": "days" }
      },
      { "type": "channel_status", "channel": "email", "consent": "subscribed" }
    ]
  },
  "contact_count": null,
  "counted_at": null,
  "created_at": "2026-03-08T12:00:00.000Z",
  "updated_at": "2026-03-08T12:00:00.000Z"
}

---

Examples

Rename only — members and count are untouched:

cURL

curl -X PATCH "https://api.arsel.sa/v1/segments/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer $ARSEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP customers (email)"
  }'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/segments/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ARSEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "VIP customers (email)",
  }),
});

const data = await response.json();
if (!response.ok) {
  throw new Error(`${data.name}: ${data.message}`);
}

console.log(data);

Python

import os

import requests

response = requests.patch(
    "https://api.arsel.sa/v1/segments/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
    headers={"Authorization": f"Bearer {os.environ['ARSEL_API_KEY']}"},
    json={
        "name": "VIP customers (email)",
    },
)
response.raise_for_status()

print(response.json())

C#

using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient(); // share one instance across requests
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("ARSEL_API_KEY"));

var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.arsel.sa/v1/segments/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a")
{
    Content = new StringContent(
        """
        {
          "name": "VIP customers (email)"
        }
        """,
        Encoding.UTF8,
        "application/json"),
};

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)response.StatusCode}: {body}");

Console.WriteLine(body);

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/segments/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("ARSEL_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "VIP customers (email)",
    ]),
]);

$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
    throw new Exception("{$data['name']}: {$data['message']}");
}

print_r($data);

---

Error Responses

422 Invalid Filter

{
  "status_code": 422,
  "name": "validation_error",
  "message": "Invalid filter: conditions.0.operator: \"created_at\" does not accept the operator \"contains\""
}

404 Not Found

{
  "status_code": 404,
  "name": "not_found",
  "message": "Segment with ID 01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a not found"
}

401 Unauthorized

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid API Key"
}