List segments

Most segments are computed from conditions: “everyone who ordered in the last 30 days”. A list segment holds exactly the people you name, by email, phone number or user ID. You can fill it from the dashboard, with a CSV upload or by typing people in, or from your own server through the API.

Each person you add is sent through the event pipeline as an identify event:

• Someone new becomes a profile. They appear on the People page with the traits you sent, such as the CSV’s other columns.
• Someone you already know is matched by email, phone or user ID, the same way any identify would match them, and their traits are updated.
• They enter the segment, which starts any journey triggered by entering it. Adds land within seconds.

Removing someone takes effect immediately and starts any journey triggered by leaving the segment. Adding someone who’s already in the list updates their traits but doesn’t make them enter again.

Create a list segment

Open Audience → Segments, click New segment, and choose List (upload, type or API) as the type. Once it’s saved, the segment’s page opens with a People in this list panel. That’s where you add and remove people. The panel also shows the segment’s ID, which you need for the API.

Note

If the segment is still a draft, the people you add are kept, but journeys that start when someone enters it won’t run until you publish it.

Add people from the dashboard

Upload a CSV

On the Upload CSV tab, choose a CSV file with a header row and one person per row. A file can have up to 50,000 rows and be up to 20 MB.

1. Origamy guesses which columns hold the email, phone and user ID, and you can change its picks. Each row needs at least one of them.
2. Leave Save the other columns on each person’s profile ticked to store the rest of the row as traits. If the file has first and last name columns but no name column, a name is built from them.
3. Click Add N people. The upload runs in chunks with a progress bar. Rows that can’t be used are listed by their row number in the file, with the reason (for example, an invalid email). They don’t stop the other rows.

Type people in

On the Type tab, enter one person per line: an email, phone number or user ID, then an optional name. Then click Add.

[email protected], Ada Lovelace
+2348031234567, Tunde Bakare
0803 123 4567

You can paste two columns straight from a spreadsheet.

Phone numbers

Write phone numbers in international format (+2348031234567), or in national format with a phone country set. The Phone country field above the tabs defaults to your workspace’s default phone region. A number like 0803 123 4567 is then read as a number in that country. A national number with no phone country set is rejected.

Remove people

• On the Remove tab, enter one email, phone number or user ID per line.
• Or click Remove beside anyone in the member list.

A removal only matches people already in the segment. A user ID matches that person, and an email or phone matches members whose stored email or phone is the same. Rows that match nobody are counted as not found.

Add and remove people with the API

Your server can change a list segment’s members with POST /v1/segments/{segmentId}/members on the ingestion API. The API tab on the segment’s page shows a ready-to-use curl command for your workspace.

Authentication

This endpoint only accepts a secret key (sk_…) from one of your server sources. Use HTTP Basic auth, with the key as the username and an empty password. Public write keys get 403, and so does any request with an Origin header, because a segment’s membership decides who receives your messages.

Caution

Never put a secret key in a browser, a mobile app, or any other code your users can read.

Add people

curl -X POST https://events.origamy.io/v1/segments/42/members \
  -u "sk_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [
      { "email": "[email protected]", "traits": { "first_name": "Jane", "city": "Lagos" } },
      { "phone": "0803 123 4567" },
      { "userId": "user-42" }
    ],
    "phoneRegion": "NG"
  }'

Remove people

curl -X POST https://events.origamy.io/v1/segments/42/members \
  -u "sk_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "remove": [
      { "email": "[email protected]" },
      { "userId": "user-7" }
    ]
  }'

One request can add and remove at the same time. Removals apply before the response is sent. Adds are queued and land within seconds.

If you run a self-hosted (BYOD) data plane, use your gateway’s host instead of events.origamy.io.

Request body

Field	Description
add	People to add.
remove	People to remove.
phoneRegion	Optional. ISO 3166 alpha-2 country (such as NG or GB) for phone numbers written without a country code.

Each person is an object with at least one of these fields:

Field	Description
email	Email address.
phone	Phone number, in E.164 (+2348031234567) or national format with phoneRegion.
userId	Your ID for the person. user_id is also accepted.
traits	Optional, adds only. Stored on the person’s profile: up to 100 keys and 16 KB per person. Empty values are skipped.

A request can hold up to 1,000 rows, counting add and remove together. Split longer lists into several requests.

Response

200 means the write was accepted:

{
  "segment_id": 42,
  "added": 2,
  "removed": 0,
  "not_found": 0,
  "rejected": [
    { "list": "add", "index": 1, "error": "\"0803 123\" is not a usable phone number" }
  ]
}

Field	Description
added	Rows queued for adding. These people appear in the segment within seconds.
removed	People removed.
not_found	Removal rows that matched nobody in the segment.
rejected	Rows that couldn’t be used. list is add or remove, and index is the row’s position in that list, counting from 0. Rejected rows don’t stop the others.

Errors

If the whole request is refused, the response is JSON with an error message and, for most errors, a code:

{
  "error": "this segment is computed from conditions; only list (manual) segments take people by name",
  "code": "segment_not_list"
}

Status	code	Meaning
400	invalid_request	Malformed body, no rows, or more than 1,000 rows.
401		Missing or unknown key.
403		Not a secret key, or the request has an Origin header.
404	segment_not_found	No segment with this ID in the key’s workspace.
409	segment_not_list	The segment is computed from conditions, so it can’t take people by name.
409	segment_managed	The segment mirrors a group or status and is kept up to date automatically.
429		Rate limited. Retry after Retry-After seconds.
503	unavailable	The segment service didn’t answer. Retry with backoff.

Adding and removing are safe to retry. Re-adding a member only refreshes their traits, and removing someone who has already left is counted as not found. A row rejected with “could not be queued; send it again” can be sent again as it is.