Create a person

POST

people

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

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

const { data, error } = await norbelys.people.create({ email: "[email protected]" });
if (error) {
  throw new Error(error.error.message);
}
console.log(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",
  "privateNotes": "Met at SaaStr; wants a demo in Q3.",
  "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"
}

{
  "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_….

Headers

Idempotency-Key

string

Opt-in idempotency for a safely retried write: reuse the same key to replay the original result for 24h instead of re-executing. Recommended on every POST.

Maximum string length: 255

Body

application/json

string<email>

required

The person's email address.

Example:

"[email protected]"

customFields

object

Custom field values keyed by code (see the Fields page).

Show child attributes

Example:

{ "company": "Acme Inc" }

familyName

string

The person's last name.

Example:

"Lovelace"

givenName

string

The person's first name.

Example:

"Ada"

source

enum<string>

Where this person came from: csv_import, manual, api, form, inbound, integration. Defaults to manual.

Available options:

csv_import,

manual,

api,

form,

inbound,

integration

Example:

"api"

telephone

string

The primary telephone number. Normalized to E.164 on write; an invalid number is dropped (the person still saves), never fatal.

Example:

"+14155550132"

telephones

string[]

Additional telephone numbers. Merged with telephone, normalized to E.164, deduped; invalid entries are dropped.

Example:

["+573163586947", "+573105550132"]

timezone

string

The person's IANA timezone, used by campaigns configured for recipient-local sending.

Example:

"America/New_York"

Response

customFields

object | null

required

Custom field values, keyed by each field's code (the merge tag). Define fields on the Fields page.

Show child attributes

Example:

{ "company": "Acme Inc", "plan": "growth" }

string<email> | null

required

The person's email address.

Example:

"[email protected]"

emailDomain

string | null

required

The domain portion of the email address.

Example:

"acme.com"

emailSendable

boolean | null

required

System-owned sendability verdict. False means the address must not be enrolled or emailed; null means it has not been verified yet.

Example:

true

familyName

string | null

required

The person's last name.

Example:

"Lovelace"

givenName

string | null

required

The person's first name.

Example:

"Ada"

string

required

The person id.

Example:

"con_tz4a98xat96iws9zmbrgj3a"

importId

string | null

required

The CSV import batch that created this person, if any.

Example:

"imp_tz4a98xat96iws9zmbrgj3a"

privateNotes

string | null

required

A private note about this person, visible only in your dashboard.

Example:

"Met at SaaStr; wants a demo in Q3."

score

integer | null

required

Engagement score, 0–100 (system-computed).

Required range: 0 <= x <= 100

Example:

42

source

enum<string>

required

Where the person came from: csv_import, manual, api, form, inbound, integration.

Available options:

csv_import,

manual,

api,

form,

inbound,

integration

Example:

"csv_import"

status

enum<string>

required

Lifecycle status: active, replied, bounced, undeliverable, spam, unsubscribed, finished.

Available options:

active,

replied,

bounced,

undeliverable,

spam,

unsubscribed,

finished

Example:

"active"

telephone

string | null

required

The PRIMARY telephone number (E.164), if known.

Example:

"+14155550132"

telephones

string[] | null

required

EVERY known telephone number (E.164), primary first — telephone is always telephones[0]. Null when none.

Example:

["+573163586947", "+573105550132"]

timezone

string | null

required

The person's IANA timezone. Campaigns using timezoneSource: recipient evaluate their send window in this timezone.

Example:

"America/New_York"

archivedAt

any

When this person was archived, or null if still active.

createdAt

any

When the person was created (RFC 3339 timestamp).

Example:

"2026-05-20T09:00:00.000Z"

lastActivityAt

any

When the person last had outbound or inbound activity (RFC 3339).

Example:

"2026-06-01T12:30:00.000Z"

object

any

default:person

Always "person". Identifies the resource type.

updatedAt

any

When the person was last updated (RFC 3339 timestamp).

Example:

"2026-06-01T12:30:00.000Z"

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

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

const { data, error } = await norbelys.people.create({ email: "[email protected]" });
if (error) {
  throw new Error(error.error.message);
}
console.log(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",
  "privateNotes": "Met at SaaStr; wants a demo in Q3.",
  "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"
}

{
  "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

Headers

Body

Response