API reference

Segments.

Save a live filter on a contact book and read who matches it. Every request needs an API key in the Authorization header; the reference overview covers keys, errors and rate limits.

List segments

GET/v1/contactBooks/{contactBookId}/segmentsFull access key

List a contact book's segments, oldest first. Each carries its live count and any problems that make it match nothing.

Path parameters
Field	Type	About
`contactBookId`required	`string`

terminal

curl -X GET "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/segments" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.segments.list("cb_123");
data?.data.forEach((segment) => console.log(segment.name, segment.count));

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

segments, _ = notix.segments.list("cb_123")
for segment in segments["data"]:
    print(segment["name"], segment["count"])

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$segments = $notix->segments->list('cb_123');
foreach ($segments['data'] as $segment) {
    echo $segment['name'], ' ', $segment['count'], PHP_EOL;
}

Responses

200The contact book's segments, oldest first, each with its live count.

200 response fields
Field	Type	About
`data`required	`object[]`
`data[].id`required	`string`
`data[].contactBookId`required	`string`
`data[].name`required	`string`
`data[].description`required	`string`	Can be null.
`data[].definition`required	`object`
`data[].definition.version`required	`number`	One of `1`.
`data[].definition.match`required	`string`	One of `all`, `any`.
`data[].definition.conditions`required	`object[]`
`data[].count`required	`integer`	Contacts that match right now. 0 while the segment has problems.
`data[].problems`required	`string[]`	Why the segment matches nothing, such as a property removed from the contact book.
`data[].createdAt`required	`string`
`data[].updatedAt`required	`string`

404No contact book with this id for the calling team.

Create a segment

POST/v1/contactBooks/{contactBookId}/segmentsFull access key

Create a live filter on a contact book. A segment is evaluated whenever it is used, so contacts join and leave it as their details and behaviour change.

Definition

match is all or any, and conditions holds up to 20 conditions, counting those inside groups. A condition can be a group with its own match; groups do not nest.

type	Operators	Fields
`email`	`equals`, `not_equals`, `contains`, `ends_with`	`value`
`first_name`, `last_name`	`equals`, `not_equals`, `contains`, `is_set`, `is_empty`	`value`, except for `is_set` and `is_empty`
`subscribed`	`is`	`value`: true or false
`added`	`before`, `after`, `in_last_days`	`value`: a date, or a number of days
`property`	`equals`, `not_equals`, `contains`, `is_set`, `is_empty`, `gt`, `gte`, `lt`, `lte`	`key` (a variable on the book) and `value`
`email_activity`	`in_last_days`, `ever`, `never`	`event`: `received`, `opened` or `clicked`; optional `campaignId`; `days` for `in_last_days`
`email_problem`	`ever`, `never`	`event`: `bounced` or `complained`
`journey`	`is_in`, `completed`, `exited`, `not_in`	`journeyId`

Text comparisons ignore case. A contact book holds at most 100 segments.

json

{
  "name": "Engaged Pro users",
  "definition": {
    "version": 1,
    "match": "all",
    "conditions": [
      { "type": "property", "key": "plan", "op": "equals", "value": "Pro" },
      {
        "type": "group",
        "match": "any",
        "conditions": [
          { "type": "email_activity", "event": "opened", "op": "in_last_days", "days": 30 },
          { "type": "email_activity", "event": "clicked", "op": "in_last_days", "days": 30 }
        ]
      }
    ]
  }
}

Path parameters
Field	Type	About
`contactBookId`required	`string`

Request body (JSON)
Field	Type	About
`name`required	`string`	At most 80 characters.
`description`	`string`	At most 280 characters. Can be null.
`definition`required	`object`
`definition.version`required	`number`	One of `1`.
`definition.match`required	`string`	One of `all`, `any`.
`definition.conditions`required	`object[]`

terminal

curl -X POST "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/segments" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Engaged Pro users",
  "definition": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "type": "property",
        "key": "plan",
        "op": "equals",
        "value": "Pro"
      },
      {
        "type": "email_activity",
        "event": "opened",
        "op": "in_last_days",
        "days": 30
      }
    ]
  }
}'

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.segments.create("cb_123", {
  name: "Engaged Pro users",
  definition: {
    version: 1,
    match: "all",
    conditions: [
      { type: "property", key: "plan", op: "equals", value: "Pro" },
      { type: "email_activity", event: "opened", op: "in_last_days", days: 30 },
    ],
  },
});

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

segment, _ = notix.segments.create(
    "cb_123",
    {
        "name": "Engaged Pro users",
        "definition": {
            "version": 1,
            "match": "all",
            "conditions": [
                {"type": "property", "key": "plan", "op": "equals", "value": "Pro"},
                {"type": "email_activity", "event": "opened", "op": "in_last_days", "days": 30},
            ],
        },
    },
)

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$segment = $notix->segments->create('cb_123', [
    'name' => 'Engaged Pro users',
    'definition' => [
        'version' => 1,
        'match' => 'all',
        'conditions' => [
            ['type' => 'property', 'key' => 'plan', 'op' => 'equals', 'value' => 'Pro'],
            ['type' => 'email_activity', 'event' => 'opened', 'op' => 'in_last_days', 'days' => 30],
        ],
    ],
]);

Responses

201The segment was created.

201 response fields
Field	Type	About
`id`required	`string`
`contactBookId`required	`string`
`name`required	`string`
`description`required	`string`	Can be null.
`definition`required	`object`
`definition.version`required	`number`	One of `1`.
`definition.match`required	`string`	One of `all`, `any`.
`definition.conditions`required	`object[]`
`count`required	`integer`	Contacts that match right now. 0 while the segment has problems.
`problems`required	`string[]`	Why the segment matches nothing, such as a property removed from the contact book.
`createdAt`required	`string`
`updatedAt`required	`string`

400The definition is not valid, names something the book or team does not have, or the book already has 100 segments.

404No contact book with this id for the calling team.

409A segment with this name already exists in the contact book.

Get a segment

GET/v1/contactBooks/{contactBookId}/segments/{segmentId}Full access key

Retrieve one segment with its definition, live count and problems.

Path parameters
Field	Type	About
`contactBookId`required	`string`
`segmentId`required	`string`

terminal

curl -X GET "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/segments/<segmentId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.segments.get("cb_123", "seg_123");

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

segment, _ = notix.segments.get("cb_123", "seg_123")

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$segment = $notix->segments->get('cb_123', 'seg_123');

Responses

200The segment with its live count.

200 response fields
Field	Type	About
`id`required	`string`
`contactBookId`required	`string`
`name`required	`string`
`description`required	`string`	Can be null.
`definition`required	`object`
`definition.version`required	`number`	One of `1`.
`definition.match`required	`string`	One of `all`, `any`.
`definition.conditions`required	`object[]`
`count`required	`integer`	Contacts that match right now. 0 while the segment has problems.
`problems`required	`string[]`	Why the segment matches nothing, such as a property removed from the contact book.
`createdAt`required	`string`
`updatedAt`required	`string`

404No segment with this id in the contact book for the calling team.

Update a segment

PATCH/v1/contactBooks/{contactBookId}/segments/{segmentId}Full access key

Change a segment's name, description or definition. A segment that a scheduled or running campaign, or an active journey, uses can be renamed but not redefined.

Path parameters
Field	Type	About
`contactBookId`required	`string`
`segmentId`required	`string`

Request body (JSON)
Field	Type	About
`name`	`string`	At most 80 characters.
`description`	`string`	At most 280 characters. Can be null.
`definition`	`object`
`definition.version`required	`number`	One of `1`.
`definition.match`required	`string`	One of `all`, `any`.
`definition.conditions`required	`object[]`

terminal

curl -X PATCH "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/segments/<segmentId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Engaged Pro users (30 days)"
}'

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.segments.update("cb_123", "seg_123", { name: "Engaged Pro and Team users" });

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

segment, _ = notix.segments.update("cb_123", "seg_123", {"name": "Engaged Pro and Team users"})

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$segment = $notix->segments->update('cb_123', 'seg_123', ['name' => 'Engaged Pro and Team users']);

Responses

200The segment after the change.

200 response fields
Field	Type	About
`id`required	`string`
`contactBookId`required	`string`
`name`required	`string`
`description`required	`string`	Can be null.
`definition`required	`object`
`definition.version`required	`number`	One of `1`.
`definition.match`required	`string`	One of `all`, `any`.
`definition.conditions`required	`object[]`
`count`required	`integer`	Contacts that match right now. 0 while the segment has problems.
`problems`required	`string[]`	Why the segment matches nothing, such as a property removed from the contact book.
`createdAt`required	`string`
`updatedAt`required	`string`

400The definition is not valid, or a live campaign or journey uses the segment and the definition changed.

404No segment with this id in the contact book for the calling team.

409Another segment in the contact book already has this name.

Delete a segment

DELETE/v1/contactBooks/{contactBookId}/segments/{segmentId}Full access key

Delete a segment. Refused with 400 while a scheduled or running campaign, or an active journey, uses it.

Path parameters
Field	Type	About
`contactBookId`required	`string`
`segmentId`required	`string`

terminal

curl -X DELETE "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/segments/<segmentId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.segments.delete("cb_123", "seg_123");

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

result, _ = notix.segments.delete("cb_123", "seg_123")

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$notix->segments->delete('cb_123', 'seg_123');

Responses

200The segment was deleted.

200 response fields
Field	Type	About
`id`required	`string`
`deleted`required	`boolean`	One of `true`.

400A scheduled or running campaign, or an active journey, uses the segment.

404No segment with this id in the contact book for the calling team.

List a segment's contacts

GET/v1/contactBooks/{contactBookId}/segments/{segmentId}/contactsFull access key

Page through the contacts that match a segment right now, ordered by id. Pass nextCursor back as cursor for the next page; limit is 1 to 100 (50 by default).

Path parameters
Field	Type	About
`contactBookId`required	`string`
`segmentId`required	`string`

Query parameters
Field	Type	About
`cursor`	`string`
`limit`	`integer`	Contacts per page, 1 to 100. Defaults to 50. Default `50`.

terminal

curl -X GET "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/segments/<segmentId>/contacts" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

let cursor: string | undefined;
do {
  const { data } = await notix.segments.contacts("cb_123", "seg_123", { cursor, limit: 100 });
  data?.data.forEach((contact) => console.log(contact.email));
  cursor = data?.nextCursor ?? undefined;
} while (cursor);

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

cursor = None
while True:
    page, _ = notix.segments.contacts("cb_123", "seg_123", cursor=cursor, limit=100)
    for contact in page["data"]:
        print(contact["email"])
    cursor = page["nextCursor"]
    if cursor is None:
        break

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$cursor = null;
do {
    $page = $notix->segments->contacts('cb_123', 'seg_123', array_filter(['cursor' => $cursor, 'limit' => 100]));
    foreach ($page['data'] as $contact) {
        echo $contact['email'], PHP_EOL;
    }
    $cursor = $page['nextCursor'];
} while ($cursor !== null);

Responses

200A page of matching contacts ordered by id, with the cursor for the next page and the total.

200 response fields
Field	Type	About
`data`required	`object[]`
`data[].id`required	`string`
`data[].email`required	`string`
`data[].firstName`required	`string`	Can be null.
`data[].lastName`required	`string`	Can be null.
`data[].subscribed`required	`boolean`
`data[].properties`required	`map of any`
`data[].createdAt`required	`string`
`data[].updatedAt`required	`string`
`nextCursor`required	`string`	Can be null.
`total`required	`integer`

400Invalid cursor or limit.

404No segment with this id in the contact book for the calling team.

422The segment took longer than 10 seconds to evaluate.