Skip to content
Norbelys
Esc
↑↓navigate↵open⌘Jpreview

Create a segment; the response counts its people.

POST/v1/segments
Authorization
AuthorizationBearer token · headerrequired

An API key (nb_live_…, nb_test_…), a workspace token (nbs_…) or a CLI token (nbc_…).

Header parameters
Idempotency-Keystringrequired

A stable key for this logical request; reuse it when retrying.

min length 1 · max length 128 · matches ^[!-~]+$
Request body
requiredapplication/json
filterFilterrequired

A segment's filter, as written and stored.

Show properties
conditionsCondition[]required

The conditions, 1 to 20.

min items 1 · max items 20
Show properties
Array of Condition
fieldstringrequired

email, email_domain, given_name, family_name, company, created_at, or a custom field as fields.<key>.

operatorOperatorrequired

How a condition compares.

Allowed:equalsnot_equalsinstarts_withexistsnot_existsgtgteltlte
valueany

What the field is compared with: absent for exists and not_exists, a list of 1 to 100 values for in, one value of the field's type otherwise (an RFC 3339 instant for created_at).

matchCombine

How a filter's conditions combine.

Allowed:allany
namestringrequired

1 to 200 characters.

Responses
201

The segment.

computed_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
created_atTimestamprequired
filterFilterrequired

A segment's filter, as written and stored.

Show properties
conditionsCondition[]required

The conditions, 1 to 20.

min items 1 · max items 20
Show properties
Array of Condition
fieldstringrequired

email, email_domain, given_name, family_name, company, created_at, or a custom field as fields.<key>.

operatorOperatorrequired

How a condition compares.

Allowed:equalsnot_equalsinstarts_withexistsnot_existsgtgteltlte
valueany

What the field is compared with: absent for exists and not_exists, a list of 1 to 100 values for in, one value of the field's type otherwise (an RFC 3339 instant for created_at).

matchCombine

How a filter's conditions combine.

Allowed:allany
idId_Segmentrequired
matches ^seg_[0-9a-f]{32}$
namestringrequired
people_countinteger<int64> | null

The people the filter matches, counted when the segment is retrieved, up to 10,000; null in a list.

people_count_cappedboolean | null

True when more than 10,000 people match; null in a list.

updated_atTimestamprequired
versioninteger<int64>required

The segment's version, also the response's ETag: updated_at in microseconds since the Unix epoch. An update sent with it in If-Match applies only to this version, so a replaced filter never undoes a change made since it was read.

401

No valid credential.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

403

The credential lacks people:write.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

422

The body or the filter is invalid.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.norbelys.com/v1/segments' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "filter": {
    "conditions": [
      {
        "field": "fields.tier",
        "operator": "equals",
        "value": "gold"
      },
      {
        "field": "email_domain",
        "operator": "not_equals",
        "value": "gmail.com"
      }
    ],
    "match": "all"
  },
  "name": "Gold accounts"
}'
Response
{
  "computed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "filter": {
    "conditions": [
      {
        "field": "string",
        "operator": "equals",
        "value": null
      }
    ],
    "match": "all"
  },
  "id": "seg_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "name": "string",
  "people_count": 0,
  "people_count_capped": true,
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}