Update a person

PATCH

people

{id}

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

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

const { data, error } = await norbelys.people.update("con_b2n4x8mq1w7e", { customFields: { company: "Acme Inc", plan: "growth" }, familyName: "Lovelace", givenName: "Ada", privateNotes: "Met at SaaStr; wants a demo in Q3." });
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",
  "enrollments": [
    {
      "assignedSenderId": "snd_pfh0haxfpzowht3oi213cqos",
      "currentStepId": "stp_m8k2w9qe4r7t1y5u3i0o6pl2",
      "id": "enr_w1x5c9v3b7n2m6k0j4h8g2fd",
      "personId": "con_tz4a98xat96iws9zmbrgj3a",
      "programId": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
      "status": "active",
      "person": {
        "email": "<string>",
        "id": "<string>",
        "name": "<string>"
      },
      "program": {
        "id": "<string>",
        "name": "<string>"
      },
      "archivedAt": "<unknown>",
      "createdAt": "<unknown>",
      "nextSendAt": "<unknown>",
      "object": "enrollment",
      "updatedAt": "<unknown>"
    }
  ],
  "groups": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "<string>"
    }
  ],
  "segments": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "timeline": [
    {
      "contactEmail": "[email protected]",
      "contactName": "<string>",
      "id": "act_y3rgwmhkbgxxa2qzmfyrdj0e",
      "personId": "con_mfyrdj0ey3rgwmhkbgxxa2qz",
      "senderId": "snd_y3rgwmhkbgxxa2qzmfyrdj0e",
      "subject": "Quick question, Ada",
      "threadId": "<string>",
      "channel": "email",
      "direction": "outbound",
      "failureCode": "dlq_exhausted",
      "isTest": true,
      "programId": "prg_a2qzmfyrdj0ey3rgwmhkbgxx",
      "status": "sent",
      "stepId": "stp_mfyrdj0ey3rgwmhkbgxxa2qz",
      "object": "message",
      "occurredAt": "2026-06-10T15:04:05.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_….

Path Parameters

string

required

The person id to update.

Example:

"con_tz4a98xat96iws9zmbrgj3a"

Body

application/json

customFields

object | null

Replaces the person's entire set of custom-field values, keyed by code.

Show child attributes

Example:

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

familyName

string | null

The person's last name.

Example:

"Lovelace"

givenName

string | null

The person's first name.

Example:

"Ada"

privateNotes

string | null

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

Example:

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

status

enum<string>

Set the lifecycle status: active, replied, bounced, undeliverable, spam, unsubscribed, finished. Bounced and spam people are terminal and cannot be reactivated through this endpoint.

Available options:

active,

replied,

bounced,

undeliverable,

spam,

unsubscribed,

finished

Example:

"unsubscribed"

telephone

string | null

Set the PRIMARY telephone number (normalized to E.164; it becomes telephones[0], keeping the person's other numbers). Null clears ALL the person's numbers. An invalid number is dropped (no change), never fatal.

Example:

"+14155550132"

telephones

string[] | null

REPLACE the person's full number set (normalized to E.164, deduped, first = primary; invalid entries dropped). Null clears all numbers.

Example:

["+573163586947", "+573105550132"]

timezone

string | null

Set the person's IANA timezone, or null to clear it. Recipient-local campaigns fall back to their own timezone when it is absent.

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"

enrollments

Enrollment · object[]

Expansion: the person's enrollments across all campaigns.

Show child attributes

groups

PersonGroupRef · object[]

Expansion: the static groups this person belongs to.

Show child attributes

segments

PersonSegmentRef · object[]

Expansion: the dynamic segments this person currently matches.

Show child attributes

timeline

(OutboundMessage · object | InboundMessage · object)[]

Expansion: the person's merged sent + received messages, newest first.

OutboundMessage
InboundMessage

Show child attributes

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

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

const { data, error } = await norbelys.people.update("con_b2n4x8mq1w7e", { customFields: { company: "Acme Inc", plan: "growth" }, familyName: "Lovelace", givenName: "Ada", privateNotes: "Met at SaaStr; wants a demo in Q3." });
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",
  "enrollments": [
    {
      "assignedSenderId": "snd_pfh0haxfpzowht3oi213cqos",
      "currentStepId": "stp_m8k2w9qe4r7t1y5u3i0o6pl2",
      "id": "enr_w1x5c9v3b7n2m6k0j4h8g2fd",
      "personId": "con_tz4a98xat96iws9zmbrgj3a",
      "programId": "prg_b2n4x8mq1w7e9rk3v5tz0yc6",
      "status": "active",
      "person": {
        "email": "<string>",
        "id": "<string>",
        "name": "<string>"
      },
      "program": {
        "id": "<string>",
        "name": "<string>"
      },
      "archivedAt": "<unknown>",
      "createdAt": "<unknown>",
      "nextSendAt": "<unknown>",
      "object": "enrollment",
      "updatedAt": "<unknown>"
    }
  ],
  "groups": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "<string>"
    }
  ],
  "segments": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "timeline": [
    {
      "contactEmail": "[email protected]",
      "contactName": "<string>",
      "id": "act_y3rgwmhkbgxxa2qzmfyrdj0e",
      "personId": "con_mfyrdj0ey3rgwmhkbgxxa2qz",
      "senderId": "snd_y3rgwmhkbgxxa2qzmfyrdj0e",
      "subject": "Quick question, Ada",
      "threadId": "<string>",
      "channel": "email",
      "direction": "outbound",
      "failureCode": "dlq_exhausted",
      "isTest": true,
      "programId": "prg_a2qzmfyrdj0ey3rgwmhkbgxx",
      "status": "sent",
      "stepId": "stp_mfyrdj0ey3rgwmhkbgxxa2qz",
      "object": "message",
      "occurredAt": "2026-06-10T15:04:05.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

Path Parameters

Body

Response