Skip to content
/Contacts

Featurebase API (2026-01-01.nova)

Welcome to the Featurebase API. This API allows you to programmatically interact with your Featurebase organization.

This documentation reflects API version 2026-01-01.nova.

Download OpenAPI description
index.json
index.yaml
Overview
URL
https://featurebase.app
License
Proprietary
Languages
Servers
Mock server
https://docs.featurebase.app/_mock/rest-api/
Production
https://do.featurebase.app/

API Versioning

This API uses date-based versioning. Each version is identified by a release date and slug, e.g., 2026-01-01.nova.

Specifying a Version

Include the version in the request header:

Featurebase-Version: 2026-01-01.nova

Or set a default version for your organization in the dashboard settings.

Version Compatibility

  • Newer versions may add new fields to responses (always backwards-compatible)
  • Breaking changes (removed/renamed fields, changed behavior) only occur in new versions
  • Your integration will continue to work as long as you pin to a specific version

Authentication

All API requests require authentication via API key.

Include in headers:

Authorization: Bearer <api-key>

Create and manage your API keys in the Featurebase dashboard.

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

  • 2xx - Success
  • 4xx - Client errors (bad request, unauthorized, not found, etc.)
  • 5xx - Server errors (internal error)

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Post not found",
    "param": "id",
    "status": 404
  }
}

Error Types

TypeDescription
authentication_errorAuthentication failed (401)
authorization_errorPermission denied (403)
invalid_request_errorInvalid request parameters or resource not found (400, 404, 410)
api_errorServer-side error (500)
rate_limit_errorToo many requests (429)

Boards

Boards (post categories) organize feedback into distinct containers with their own settings.

Operations

Posts

User-submitted feedback and feature requests. Posts belong to boards and can be upvoted, commented on, and tracked through statuses.

Operations

Post Statuses

Post statuses define the workflow stages for posts (e.g., In Review, Active, Completed).

Operations

Comments

Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls.

Operations

Custom Fields

Configurable input fields for posts in your Featurebase organization. Custom fields allow you to collect additional structured data when users create posts.

Operations

Changelogs

Release notes and updates published by the organization. Changelogs keep users informed about new features, improvements, and fixes.

Operations

Admins

Team members who manage your Featurebase organization. Admins have roles that define their permissions.

Operations

Teams

Teams are groups within your Featurebase organization. Use this endpoint to list and retrieve team information for conversation assignment and organization management.

Operations

Contacts

Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.

Operations

List contacts

Request

Returns a list of contacts (customers and leads) in your organization using cursor-based pagination.

Query Parameters

  • limit - Number of contacts to return (1-100, default 10)
  • cursor - Cursor from previous response for pagination
  • contactType - Filter by contact type: "customer" (default), "lead", or "all"

Response Format

Returns a list object with:

  • object - Always "list"
  • data - Array of contact objects
  • nextCursor - Cursor for the next page, or null if no more results

Contact Object

Each contact includes:

  • id - Unique contact identifier
  • userId - External user ID from SSO (if set)
  • email - Contact email address
  • name - Contact display name
  • profilePicture - Profile picture URL
  • type - Contact type ("customer" or "lead")
  • companies - Array of companies the contact belongs to
  • customFields - Custom field values
  • postsCreated - Number of posts created
  • commentsCreated - Number of comments created
  • lastActivity - Last activity timestamp

Example

{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "676f0f6765bdaa7d7d760f88",
      "email": "john@example.com",
      "name": "John Doe",
      "type": "customer",
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Security
bearerAuth
Query
limitinteger[ 1 .. 100 ]

A limit on the number of objects to be returned, between 1 and 100.

Default 10
Example: limit=10
cursorstring<= 512 characters

An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.

Example: cursor=eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
contactTypestring

Filter contacts by type. Defaults to "customer".

Default "customer"
Enum"customer""lead""all"
Example: contactType=customer
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
curl -i -X GET \
  'https://docs.featurebase.app/_mock/rest-api/v2/contacts?limit=10&cursor=eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9&contactType=customer' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Featurebase-Version: 2026-01-01.nova'

Responses

Success

Bodyapplication/json
objectstringrequired

Object type identifier

Value"list"
Example: "list"
dataArray of objectsrequired

Array of contacts

Example: []
nextCursorstring or nullrequired

Cursor for fetching the next page (cursor-based pagination)

Example: "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
Response
application/json
{
  "object": "list",
  "data": [],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}

Create or update a contact

Request

Creates a new contact or updates an existing one.

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

FieldTypeRequiredDescription
emailstringOne of email/userIdContact email address
userIdstringOne of email/userIdExternal user ID from your system
namestringNoContact display name
profilePicturestringNoProfile picture URL
companiesarrayNoCompanies the contact belongs to
customFieldsobjectNoCustom field values
subscribedToChangelogbooleanNoWhether subscribed to changelog
localestringNoContact locale/language
phonestringNoContact phone number
rolesarrayNoRole IDs to assign
userHashstringNoHMAC hash for identity verification
createdAtstringNoWhen the contact was created (ISO 8601)

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 Response

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

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Security
bearerAuth
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
Bodyapplication/json
emailstring(email)<= 500 characters

Contact email address. Used for identification if userId is not provided.

Example: "john@example.com"
namestring<= 500 characters

Contact display name

Example: "John Doe"
userIdstring<= 500 characters

External user ID from your system. Takes precedence over email for identification.

Example: "usr_12345"
userHashstring<= 256 characters

HMAC-SHA256 hash of userId or email for identity verification

Example: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
profilePicturestring or null(uri)

Profile picture URL

Example: "https://example.com/avatar.png"
companiesArray of objects(UpsertContactCompany)<= 100 items

Companies the contact belongs to

createdAtstring or null

When the contact was created in your system (ISO 8601)

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

Custom field values on the contact. Values can be string, number, boolean, null, or array of primitives.

subscribedToChangelogboolean

Whether the contact is subscribed to changelog updates

Example: true
localestring<= 10 characters

Contact locale/language preference

Example: "en"
phonestring or null<= 500 characters

Contact phone number

Example: "+1234567890"
rolesArray of strings<= 100 items

Array of role IDs to assign to the contact

Example: ["role_vip","role_beta"]
curl -i -X POST \
  https://docs.featurebase.app/_mock/rest-api/v2/contacts \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Featurebase-Version: 2026-01-01.nova' \
  -d '{
    "email": "john@example.com",
    "name": "John Doe",
    "userId": "usr_12345",
    "userHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
    "profilePicture": "https://example.com/avatar.png",
    "companies": [
      {
        "id": "company_123",
        "name": "Acme Inc",
        "createdAt": "2024-01-15T10:30:00Z",
        "monthlySpend": 500,
        "customFields": {
          "plan": "enterprise",
          "industry": "Technology",
          "priority": "high"
        },
        "companyHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
        "companySize": 50,
        "industry": "Technology",
        "website": "https://acme.com",
        "plan": "enterprise"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "customFields": {
      "plan": "pro",
      "signupSource": "website",
      "accountType": "premium"
    },
    "subscribedToChangelog": true,
    "locale": "en",
    "phone": "+1234567890",
    "roles": [
      "role_vip",
      "role_beta"
    ]
  }'

Responses

Created

Bodyapplication/json
objectstringrequired

Object type identifier

Value"contact"
Example: "contact"
idstringrequired

Unique identifier

Example: "676f0f6765bdaa7d7d760f88"
userIdstring

External user ID from SSO

Example: "676f0f673dbb299c8a4f3057"
organizationIdstring

Organization ID the contact belongs to

Example: "5febde12dc56d60012d47db6"
companiesArray of objects(Company)

Companies the contact belongs to

Example: []
emailstring or null

Contact email

Example: "john@example.com"
namestringrequired

Contact display name

Example: "John Steezy"
profilePicturestring or null

Profile picture URL

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

Number of comments created

Example: 0
postsCreatednumber

Number of posts created

Example: 0
lastActivitystring

Last activity ISO timestamp

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

Whether subscribed to changelog

Example: true
manuallyOptedOutFromChangelogboolean

Whether manually opted out from changelog

Example: false
rolesArray of strings

Contact roles

Example: []
localestring

Contact locale

Example: "en"
verifiedboolean

Whether email is verified

Example: true
typestringrequired

Type of contact

Enum"customer""lead"
Example: "customer"
descriptionstring

Contact description/bio

Example: ""
customFieldsobject

Custom field values on the contact

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

Get contact by ID

Request

Retrieves a single contact by their Featurebase ID.

Returns both customers and leads.

Path Parameters

  • id - The Featurebase contact ID (24-character ObjectId)

Response Format

Returns a single contact object with:

  • object - Always "contact"
  • id - Unique contact identifier
  • userId - External user ID from SSO (if set)
  • email - Contact email address
  • name - Contact display name
  • profilePicture - Profile picture URL
  • type - Contact type ("customer" or "lead")
  • companies - Array of companies the contact belongs to
  • customFields - Custom field values
  • postsCreated - Number of posts created
  • commentsCreated - Number of comments created
  • lastActivity - Last activity timestamp

Example

{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "email": "john@example.com",
  "name": "John Doe",
  "type": "customer",
  ...
}

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Security
bearerAuth
Path
idstringrequired

Featurebase contact ID

Example: 507f1f77bcf86cd799439011
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
curl -i -X GET \
  https://docs.featurebase.app/_mock/rest-api/v2/contacts/507f1f77bcf86cd799439011 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Featurebase-Version: 2026-01-01.nova'

Responses

Success

Bodyapplication/json
objectstringrequired

Object type identifier

Value"contact"
Example: "contact"
idstringrequired

Unique identifier

Example: "676f0f6765bdaa7d7d760f88"
userIdstring

External user ID from SSO

Example: "676f0f673dbb299c8a4f3057"
organizationIdstring

Organization ID the contact belongs to

Example: "5febde12dc56d60012d47db6"
companiesArray of objects(Company)

Companies the contact belongs to

Example: []
emailstring or null

Contact email

Example: "john@example.com"
namestringrequired

Contact display name

Example: "John Steezy"
profilePicturestring or null

Profile picture URL

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

Number of comments created

Example: 0
postsCreatednumber

Number of posts created

Example: 0
lastActivitystring

Last activity ISO timestamp

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

Whether subscribed to changelog

Example: true
manuallyOptedOutFromChangelogboolean

Whether manually opted out from changelog

Example: false
rolesArray of strings

Contact roles

Example: []
localestring

Contact locale

Example: "en"
verifiedboolean

Whether email is verified

Example: true
typestringrequired

Type of contact

Enum"customer""lead"
Example: "customer"
descriptionstring

Contact description/bio

Example: ""
customFieldsobject

Custom field values on the contact

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

Companies

Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information.

Operations

Surveys

Surveys allow you to collect targeted feedback from your users within your product. Surveys can be targeted to specific user segments or pages and can contain multiple questions with conditional logic.

Operations

Help Centers

Help centers allow organizations to create and manage knowledge bases with articles and collections. Currently, Featurebase supports one help center per organization.

Operations

Conversations

Conversations are messenger/inbox conversations in your Featurebase organization. Use this endpoint to list and retrieve conversation information.

Operations

Webhooks

Webhooks allow you to receive real-time HTTP callbacks when events occur in your Featurebase organization. Configure webhook endpoints to subscribe to specific event types.

Operations