List who joined or left a segment on a dayMenu

List who joined or left a segment on a day

GET/v1/segments/{id}/membership-changes

Requires an API key with the contacts:read scope. About keys and scopes

Works with integration, agent and partner keys.

The contacts who joined (change=joined) or left (change=left) the segment on day, in the workspace timezone, newest first, from the changes recorded then (kept as long as the workspace's events). meta.count is that day's joinedCount or leftCount from getSegmentSizeHistory, on the first page only (null with a cursor), so the list and the chart agree.

Path parameters

idstringrequired

The segment's id.

uuid

Query parameters

limitintegeroptional

How many items a page holds: 1 to 100, 20 by default.

min > 0 · max 100 · default 20

cursorstringoptional

Where the page starts: the previous page's meta.pagination.nextCursor. Omit it for the first page, and send the same filters with it.

1–2,048 characters

changestringrequired

Who joined (joined) or left (left) the segment.

one of joined, left

daystringrequired

The day, YYYY-MM-DD in the workspace timezone.

date

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

Returns 200 OK with a list of ContactDetail objects in data, and the next page's cursor in meta (see pagination). Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

externalIdstring | nullrequired

Your own id for the contact, if set.

emailstring | nullrequired

firstNamestring | nullrequired

lastNamestring | nullrequired

phonestring | nullrequired

Phone number in E.164 format.

timezonestring | nullrequired

IANA timezone, e.g. Europe/London.

countrystring | nullrequired

ISO 3166-1 alpha-2 code: as written, or inferred from the phone, else the timezone.

localestring | nullrequired

BCP 47 tag (fr, fr-CA): the language the contact reads (its first subtag), and how merge tags format numbers, dates and money for them.

rfmobject | nullrequired

The contact's RFM (recency, frequency and monetary value) group among the workspace's customers, from its purchase events (the workspace's purchaseEvent: an order, a paid invoice, a booking, a donation), each score from 1 to 5 (a fifth of the customers each; 5 is the most recent, most frequent or highest spend), and their purchase totals. Spend counts only purchases in the workspace's main currency; when the purchase carries no amount, monetary follows frequency. Recomputed daily, so a purchase today shows tomorrow; null for someone who has never purchased.

7 child attributes

groupstringrequired

one of champions, loyal, cant_lose_them, potential_loyalists, new_customers, need_attention, about_to_sleep, at_risk, hibernating, lost

recencyintegerrequired

min 1 · max 5

frequencyintegerrequired

min 1 · max 5

monetaryintegerrequired

min 1 · max 5

purchaseCountintegerrequired

Their purchase events (the workspace's purchaseEvent), in any currency.

min > 0

totalSpentobject | nullrequired

What their purchases' amounts (purchaseValueProperty) add up to, in the workspace's main currency (currency on GET /v1/reports/rfm); purchases in other currencies and refunds are left out. null when the purchase carries no amount.

2 child attributes

currencystring | nullrequired: The currency, an ISO 4217 code; null when none was named.
valuenumberrequired: The amount in that currency.

lastPurchasedAtstringrequired

When their latest purchase happened.

date-time

datesmap<string, string>required

Named calendar dates, e.g. birthday, as YYYY-MM-DD or --MM-DD.

attributesmap<string, object>required

Custom attributes, keyed by attribute name.

consentContactConsentrequired

Consent on each channel.

2 child attributes

emailbooleanrequired: Whether the contact has consented to email.
pushbooleanrequired: Whether the contact has consented to push.

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

emailSuppressionobjectrequired

2 child attributes

suppressedbooleanrequired: Whether email to this contact is blocked.
reasonstring | nullrequired: Why email to this contact is suppressed: bounced, complained, complained_transactional, unsubscribed, manual, imported, or other_workspace (a bounce or complaint in another workspace with the same owner or partner).

listIdsstring[]required

Ids of the lists the contact is in.

curl 'https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/membership-changes?change=joined&day=2030-03-14' \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/membership-changes?change=joined&day=2030-03-14', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data, meta } = await response.json();
// meta.pagination.nextCursor is the next page's `cursor`, and null on the last page.

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/membership-changes?change=joined&day=2030-03-14",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
body = response.json()
data = body["data"]
next_cursor = body["meta"]["pagination"]["nextCursor"]
# next_cursor is the next page's `cursor`, and None on the last page.

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/membership-changes?change=joined&day=2030-03-14", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
		Meta struct {
			Pagination struct {
				NextCursor *string `json:"nextCursor"`
			} `json:"pagination"`
		} `json:"meta"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	// out.Meta.Pagination.NextCursor is the next page's `cursor`, and nil on the last page.
}

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

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/membership-changes?change=joined&day=2030-03-14");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

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

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");
var nextCursor = document.RootElement.GetProperty("meta").GetProperty("pagination").GetProperty("nextCursor");
// nextCursor is the next page's `cursor`, and null on the last page.

Response · 200

{
  "data": [
    {
      "id": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
      "externalId": "customer-4821",
      "email": "[email protected]",
      "firstName": "Amaka",
      "lastName": "Obi",
      "phone": "+447700900123",
      "timezone": "Europe/London",
      "country": "GB",
      "locale": "en-NG",
      "rfm": {
        "group": "loyal",
        "recency": 3,
        "frequency": 4,
        "monetary": 5,
        "purchaseCount": 6,
        "totalSpent": {
          "currency": "USD",
          "value": 412.5
        },
        "lastPurchasedAt": "2026-03-02T18:20:00.000Z"
      },
      "dates": {
        "birthday": "1992-03-14"
      },
      "attributes": {
        "plan": "pro",
        "favourite_spice": "smoked paprika",
        "orders": 3
      },
      "consent": {
        "email": true,
        "push": false
      },
      "createdAt": "2026-09-12T08:15:00.000Z",
      "updatedAt": "2026-10-01T09:30:00.000Z",
      "emailSuppression": {
        "suppressed": false,
        "reason": null
      },
      "listIds": [
        "0192f3a2-1b3c-7e5d-8a21-4f6a7b8c9d0e"
      ]
    }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "nextCursor": null
    },
    "count": 12
  }
}