Contacts

Create or update a contact

Creates a new contact or updates an existing one.

POST

/v2/contacts

curl --request POST \
  --url https://do.featurebase.app/v2/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "companies": [
    {
      "companyHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
      "companySize": 50,
      "createdAt": "2024-01-15T10:30:00Z",
      "customFields": {
        "industry": "Technology",
        "plan": "enterprise",
        "priority": "high"
      },
      "id": "company_123",
      "industry": "Technology",
      "monthlySpend": 500,
      "name": "Acme Inc",
      "plan": "enterprise",
      "website": "https://acme.com"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "customFields": {
    "accountType": null,
    "plan": "pro",
    "signupSource": "website"
  },
  "email": "john@example.com",
  "locale": "en",
  "name": "John Doe",
  "phone": "+1234567890",
  "profilePicture": "https://example.com/avatar.png",
  "roles": [
    "app",
    "role_vip",
    "role_beta",
    "Internal User"
  ],
  "subscribedToChangelog": true,
  "userHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "userId": "usr_12345"
}
'

{
  "commentsCreated": 0,
  "companies": [],
  "customFields": {},
  "description": "",
  "email": "john@example.com",
  "id": "676f0f6765bdaa7d7d760f88",
  "lastActivity": "2025-01-03T21:42:30.181Z",
  "locale": "en",
  "manuallyOptedOutFromChangelog": false,
  "name": "John Steezy",
  "object": "contact",
  "organizationId": "5febde12dc56d60012d47db6",
  "postsCreated": 0,
  "profilePicture": "https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png",
  "roles": [],
  "subscribedToChangelog": true,
  "type": "customer",
  "userId": "676f0f673dbb299c8a4f3057",
  "verified": true
}

If a contact with the given email or userId already exists, it will be updated. Otherwise, a new contact will be created.

At least one of email or userId must be provided for identification.

Request Body

Field	Type	Required	Description
`email`	string or null	One of email/userId	Contact email address. Send `null` with `userId` to remove the current email.
`userId`	string or null	One of email/userId	External user ID. Send `null` with `email` to remove it.
`name`	string or null	No	Contact display name. `null` resets it to the system fallback.
`profilePicture`	string or null	No	Profile picture URL. `null` removes it.
`companies`	array	No	Replacement company list. `[]` removes all memberships.
`customFields`	object	No	Values merge by key. A key with `null` is removed.
`subscribedToChangelog`	boolean	No	Whether subscribed to changelog
`locale`	string or null	No	Contact locale/language. `null` removes it.
`phone`	string or null	No	Contact phone number. `null` removes it.
`roles`	array	No	Replacement role list. `[]` removes all roles.
`userHash`	string	No	HMAC hash for identity verification
`createdAt`	string	No	When the contact was created (ISO 8601)

Orbit Field Update Semantics

Omit a field to keep its current value.
Send a non-null scalar value to add or replace that value.
Send null for email, userId, name, profilePicture, phone, or locale to clear or reset it.
A contact must keep at least one identifier. Removing email requires userId. Removing userId requires email.
Send an array to replace the stored list. Send [] to clear companies or roles.
customFields is merged by key. Omitted keys stay unchanged. A key with null is removed.
createdAt and subscribedToChangelog do not accept null. Use false to turn off changelog subscription.
Empty strings are not deletion values for typed contact fields.

Company Object

Each company in the companies array can have:

id (required) - External company ID from your system
name (required) - Company name
monthlySpend - Monthly spend/revenue
customFields - Custom field values
industry - Industry
website - Company website URL
plan - Current plan/subscription
companySize - Number of employees
createdAt - When the company was created

Response

Returns the created or updated contact object.

201 Created - A new contact was created
200 OK - An existing contact was updated

Example Request

{
  "email": "john@example.com",
  "name": "John Doe",
  "userId": "usr_12345",
  "companies": [
    {
      "id": "company_123",
      "name": "Acme Inc",
      "monthlySpend": 500,
      "plan": "enterprise"
    }
  ],
  "customFields": {
    "plan": "pro",
    "signupSource": "website"
  },
  "subscribedToChangelog": true
}

Example: Remove an Email

{
  "userId": "usr_12345",
  "email": null
}

Example Response

{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "email": "john@example.com",
  "name": "John Doe",
  "userId": "usr_12345",
  "type": "customer",
  "companies": [...],
  "customFields": {...},
  ...
}

Version Availability

This endpoint is available in API version 2026-01-01.nova and newer. The Orbit field update rules, including null removal and empty-array replacement, require API version 2026-08-19.orbit or newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

companiesobject[]

Replacement list of companies. Pass an empty array to remove all company memberships.

Maximum array length: 100

Show child attributes

createdAtstring

When the contact was created in your system (ISO 8601). This field cannot be null.

Example: 2024-01-15T10:30:00Z

customFieldsobject

Fields are merged by key. Omitted keys are preserved. A null value removes that custom field key.

emailstring | null

Contact email address. Omit to preserve it, or pass null with userId to remove the stored email.

Maximum string length: 500

Example: john@example.com

localestring | null

Contact locale/language preference. Pass null to remove it.

Required string length: 1 - 10

Example: en

namestring | null

Contact display name. Pass null to reset it to the system fallback.

Required string length: 1 - 500

Example: John Doe

phonestring | null

Contact phone number. Pass null to remove it.

Required string length: 1 - 500

Example: +1234567890

profilePicturestring | null

Profile picture URL. Pass null to remove the stored profile picture.

Example: https://example.com/avatar.png

rolesstring[]

Replacement list of role (User Tag) names. Pass an empty array to remove all roles.

Maximum array length: 100

subscribedToChangelogboolean

Whether the contact is subscribed to changelog updates

Example: true

userHashstring

HMAC-SHA256 hash of userId or email for identity verification

Maximum string length: 256

Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

userIdstring | null

External user ID from your system. Pass null with email to remove the stored user ID.

Required string length: 1 - 500

Example: usr_12345

Response

Created

commentsCreatednumber

Number of comments created

Example: 0

companiesobject[]

Companies the contact belongs to

Show child attributes

customFieldsobject

Custom field values on the contact

descriptionstring

Contact description/bio

Example:

emailstring | null

Contact email

Example: john@example.com

idstringrequired

Unique identifier

Example: 676f0f6765bdaa7d7d760f88

lastActivitystring

Last activity ISO timestamp

Example: 2025-01-03T21:42:30.181Z

localestring

Contact locale

Example: en

manuallyOptedOutFromChangelogboolean

Whether manually opted out from changelog

Example: false

namestringrequired

Contact display name

Example: John Steezy

objectenum<string>required

Object type identifier

Available options: contact

Example: contact

organizationIdstring

Organization ID the contact belongs to

Example: 5febde12dc56d60012d47db6

postsCreatednumber

Number of posts created

Example: 0

profilePicturestring | null

Profile picture URL

Example: https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png

rolesstring[]

Contact roles

subscribedToChangelogboolean

Whether subscribed to changelog

Example: true

typeenum<string>required

Type of contact

Available options: customer, lead

Example: customer

userIdstring

External user ID from SSO

Example: 676f0f673dbb299c8a4f3057

verifiedboolean

Whether email is verified

Example: true

Still need help? Ask the team