List people

GET

people

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.people.list();
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "data": [
    {
      "customFields": {
        "company": "Acme Inc",
        "plan": "growth"
      },
      "email": "[email protected]",
      "emailDomain": "acme.com",
      "emailSendable": true,
      "familyName": "Lovelace",
      "givenName": "Ada",
      "id": "con_tz4a98xat96iws9zmbrgj3a",
      "importId": "imp_tz4a98xat96iws9zmbrgj3a",
      "score": 42,
      "source": "csv_import",
      "status": "active",
      "telephone": "+14155550132",
      "telephones": [
        "+573163586947",
        "+573105550132"
      ],
      "timezone": "America/New_York",
      "archivedAt": "<unknown>",
      "createdAt": "2026-05-20T09:00:00.000Z",
      "lastActivityAt": "2026-06-01T12:30:00.000Z",
      "object": "person",
      "updatedAt": "2026-06-01T12:30:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "total": 1284,
  "object": "list"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Org-scoped Norbelys API key. Create one in Settings → API keys and send it as Authorization: Bearer ak_….

Query Parameters

cursor

string

Opaque cursor from a previous page's nextCursor — returns results strictly after it. Example: "con_x7q2m9k4w8r1"

includeArchived

boolean

Include archived rows in the results (hidden by default). Example: true

dir

enum<string>

Sort direction for page-based browsing. Defaults to desc. Ignored by cursor-based callers.

Available options:

asc,

desc

filter

AudienceFilterInput · object

An unsaved audience rule tree (match + conditions) — the same grammar a segment's definition uses, evaluated live. Use it to preview a draft filter: total is the match count and data the sample. Combined (AND) with search, status, source, groupId, and segmentId.

Show child attributes

Example:

{
  "conditions": [
    {
      "field": "status",
      "op": "in",
      "value": ["active"]
    }
  ],
  "match": "all"
}

groupId

string

Show only members of this group (a static list).

Example:

"grp_tz4a98xat96iws9zmbrgj3a"

limit

integer

Page size, 1–500. Defaults to 50.

Required range: 1 <= x <= 500

page

integer

One-based page number. Supplying page or sort switches to offset pagination with stable ordering.

Required range: x >= 1

string

Case-insensitive free-text search over email, name, and custom-field values.

Example:

"ada"

segmentId

string

Show only people currently matching this segment (a saved filter), evaluated live.

Example:

"seg_tz4a98xat96iws9zmbrgj3a"

sort

enum<string>

Sort field for the results. Supplying it enables page-based browsing; defaults to created_at.

Available options:

created_at,

email,

last_activity_at,

name,

score

source

enum<string>[]

Match any of these sources: csv_import, manual, api, form, inbound, integration.

Available options:

csv_import,

manual,

api,

form,

inbound,

integration

Example:

["csv_import"]

status

enum<string>[]

Match any of these lifecycle statuses: active, replied, bounced, undeliverable, spam, unsubscribed, finished.

Available options:

active,

replied,

bounced,

undeliverable,

spam,

unsubscribed,

finished

Example:

["active", "replied"]

Response

data

PersonListItem · object[]

required

The page of results, newest first.

Show child attributes

hasMore

boolean

required

Whether another page exists beyond this one.

nextCursor

string | null

required

Pass as cursor to fetch the next page; null when this is the last page.

total

integer

required

Count of ALL people matching the filters.

Required range: x >= 0

Example:

1284

object

any

default:list

Always "list", marking this response as a collection.

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.people.list();
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "data": [
    {
      "customFields": {
        "company": "Acme Inc",
        "plan": "growth"
      },
      "email": "[email protected]",
      "emailDomain": "acme.com",
      "emailSendable": true,
      "familyName": "Lovelace",
      "givenName": "Ada",
      "id": "con_tz4a98xat96iws9zmbrgj3a",
      "importId": "imp_tz4a98xat96iws9zmbrgj3a",
      "score": 42,
      "source": "csv_import",
      "status": "active",
      "telephone": "+14155550132",
      "telephones": [
        "+573163586947",
        "+573105550132"
      ],
      "timezone": "America/New_York",
      "archivedAt": "<unknown>",
      "createdAt": "2026-05-20T09:00:00.000Z",
      "lastActivityAt": "2026-06-01T12:30:00.000Z",
      "object": "person",
      "updatedAt": "2026-06-01T12:30:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "total": 1284,
  "object": "list"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Analytics

Domains

Fields

Files

Groups

Integrations

Messages

Organization

People

Programs

Segments

Senders

Suppressions

Verify

Authorizations

Query Parameters

Response