Skip to main content
POST

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
​
label
string
required

The human-readable display name for the field.

Required string length: 1 - 100
Example:

"Favorite category"

​
code
string

The merge code; omit to auto-derive a slug from the label.

Required string length: 1 - 50
Pattern: ^[a-z][a-z0-9_]*$
Example:

"favorite_category"

​
defaultValue

Value applied when a new/imported contact omits this field; null or an empty string disables it.

Maximum string length: 1000
​
isFilterable
boolean

Offer this field as a segment filter; defaults to true.

Example:

true

​
options
string[]

Allowed values — required when type is dropdown.

Maximum array length: 100
Minimum string length: 1
Example:
​
type
enum<string>
default:text

The data type: text, email, phone, date, datetime, number, or dropdown; defaults to text.

Available options:
text,
email,
phone,
date,
datetime,
number,
dropdown
Example:

"dropdown"

Response

OK

​
code
string
required

The merge tag and storage key, templated as {{ code }}.

Example:

"favorite_category"

​
defaultValue
required

The value applied to new/imported contacts that omit this field, or null when disabled.

Maximum string length: 1000
​
id
string
required

The field id.

Example:

"fld_tz4a98xat96iws9zmbrgj3a"

​
isFilterable
boolean
required

Whether this field is offered as a segment/list filter.

Example:

true

​
label
string
required

The human-readable display name for the field.

Example:

"Favorite category"

​
options
string[] | null
required

Allowed values for a dropdown field; null for other types.

Example:
​
order
integer
required

Display order among custom fields (lower = first).

Required range: x >= 0
Example:

0

​
type
enum<string>
required

The data type: text, email, phone, date, datetime, number, or dropdown. email and phone values are validated on write: a phone is normalized to E.164, and an invalid value is dropped without failing the request.

Available options:
text,
email,
phone,
date,
datetime,
number,
dropdown
Example:

"dropdown"

​
archivedAt
any

When the field was archived (RFC 3339), or null if still active.

​
createdAt
any

When the field was created (RFC 3339).

​
object
any
default:field

Always "field" — the resource discriminator.

​
updatedAt
any

When the field was last updated (RFC 3339).