API Reference

Users

Companies

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Search companies

POST/v2/companies/search

Search companies with a structured filter AST, sorting, and cursor pagination.

Structured query AST

Each clause has the shape { field, operator, value }. You can pass a single clause or wrap up to 15 in a top-level AND group:

{
  "query": {
    "operator": "AND",
    "value": [
      { "field": "plan", "operator": "IN", "value": ["enterprise", "pro"] },
      { "field": "monthlySpend", "operator": ">", "value": 1000 }
    ]
  },
  "sort": "monthlySpend:desc",
  "limit": 20
}

Top-level OR groups and nested groups are not supported in this version.

Supported fields and operators

Field names are camelCase, matching the rest of the v2 public API. Snake_case names that this endpoint originally shipped with (external_id, monthly_spend, company_size, linked_users, last_activity, created_at) are still accepted for back-compat but are deprecated — please migrate to camelCase in new code.

Field	Type	Operators
externalId	string (caller-provided company id)	=, !=, IN, NIN
name	string	=, !=, IN, NIN, ~
monthlySpend	number	=, !=, >, <
plan	string	=, !=, IN, NIN
industry	string	=, !=, IN, NIN
website	string	=, !=, IN, NIN
companySize	number	=, !=, >, <
linkedUsers	number	=, !=, >, <
lastActivity	unix seconds	=, !=, >, <
createdAt	unix seconds	=, !=, >, <

The name ~ "..." operator runs a word-aware substring search via the underlying text index. Other string operators (!~, ^, $) are reserved for future use and currently return 400.

A query consisting only of != or NIN clauses is rejected with query_too_broad to prevent full-org scans. Combine the negation with at least one positive clause (=, IN, >, <) instead.

Sort

Allowed values:

• createdAt:desc (default), createdAt:asc
• monthlySpend:desc, monthlySpend:asc
• lastActivity:desc, lastActivity:asc

Snake_case sort axes (created_at:desc, monthly_spend:asc, last_activity:desc) are accepted for back-compat — the cursor encodes the canonical camelCase identity, so a caller can switch naming conventions mid-pagination without restarting.

The chosen sort axis is encoded in the cursor; switching sort mid-pagination returns 400 invalid_cursor. Restart pagination without a cursor when changing sort.

Pagination

Cursor-based, limit between 1 and 100 (default 10). totalCount is approximate and capped at 5000; totalCountCapped is true when the real count may be higher.

Response

Returns a standard list envelope with company rows identical to GET /v2/companies/{id}.

Version Availability

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

Header ParametersExpand Collapse

"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"

One of the following:

"2026-01-01.nova"

"2025-12-12.clover"

Body ParametersJSONExpand Collapse

cursor: optional string

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

maxLength512

limit: optional number

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

minimum1

maximum100

query: optional object { field, operator, value } or object { operator, value }

Structured filter AST. Either a single filter clause or one top-level AND group (max 15 clauses). Top-level OR groups are not yet supported.

One of the following:

SearchFilter object { field, operator, value }

field: string

Field name to filter on (e.g. state, tag_ids, created_at)

minLength1

maxLength64

operator: "=" or "!=" or "IN" or 9 more

Comparison operator

One of the following:

"="

"!="

"IN"

"NIN"

">"

"<"

">="

"<="

"~"

"!~"

"^"

"$"

value: string or number or boolean or array of string or number

Value to compare against (primitive or array of primitives)

One of the following:

string

number

boolean

array of string or number

One of the following:

string

number

SearchFilterGroup object { operator, value }

operator: "AND" or "OR"

Group operator: AND (all match) or OR (any match)

One of the following:

"AND"

"OR"

value: array of object { field, operator, value }

Array of filter clauses (1-15 entries)

field: string

Field name to filter on (e.g. state, tag_ids, created_at)

minLength1

maxLength64

operator: "=" or "!=" or "IN" or 9 more

Comparison operator

One of the following:

"="

"!="

"IN"

"NIN"

">"

"<"

">="

"<="

"~"

"!~"

"^"

"$"

value: string or number or boolean or array of string or number

Value to compare against (primitive or array of primitives)

One of the following:

string

number

boolean

array of string or number

One of the following:

string

number

sort: optional "createdAt:desc" or "createdAt:asc" or "monthlySpend:desc" or 9 more

Sort field + direction. Defaults to createdAt:desc. The chosen sort axis is encoded in the cursor; switching sort mid-pagination returns 400 invalid_cursor. Snake_case names (created_at:desc, monthly_spend:asc, last_activity:desc) are accepted for back-compat — prefer camelCase in new code.

One of the following:

"createdAt:desc"

"createdAt:asc"

"monthlySpend:desc"

"monthlySpend:asc"

"lastActivity:desc"

"lastActivity:asc"

"created_at:desc"

"created_at:asc"

"monthly_spend:desc"

"monthly_spend:asc"

"last_activity:desc"

"last_activity:asc"

ReturnsExpand Collapse

data: array of object { id, companyId, companySize, 11 more }

Array of search results

id: string

Featurebase internal ID

companyId: string

External company ID from your system

companySize: number

Company employee headcount

createdAt: string

ISO date when company was created

industry: string

Industry

lastActivity: string

ISO date of last activity

linkedUsers: number

Number of users linked to this company

monthlySpend: number

Monthly spend

name: string

Company name

object: "company"

Object type identifier

plan: string

Plan or tier name

updatedAt: string

ISO date when company was last updated

website: string

Company website URL

customFields: optional map[unknown]

Custom field values

nextCursor: string

Cursor for fetching the next page (null if no more results)

object: "list"

Object type identifier

totalCount: optional number

Total number of companies matching the query, capped at 5000. When the actual total is at or above the cap, totalCountCapped is true and the value is exactly the cap.

totalCountCapped: optional boolean

True when totalCount is exactly the cap and the real count may be higher. UI can render as e.g. “5000+”.

Search companies

HTTP

HTTP

TypeScript

curl https://do.featurebase.app/v2/companies/search \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY" \
    -d '{
          "cursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
          "limit": 10,
          "sort": "createdAt:desc"
        }'

200 example

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "companyId": "comp_12345",
      "companySize": 250,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "industry": "Technology",
      "lastActivity": "2025-01-15T00:00:00.000Z",
      "linkedUsers": 15,
      "monthlySpend": 5000,
      "name": "Acme Inc",
      "object": "company",
      "plan": "enterprise",
      "updatedAt": "2025-01-10T15:30:00.000Z",
      "website": "https://acme.com",
      "customFields": {
        "location": "bar",
        "priority": "bar"
      }
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
  "object": "list",
  "totalCount": 42,
  "totalCountCapped": false
}

Returns Examples

200 example

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "companyId": "comp_12345",
      "companySize": 250,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "industry": "Technology",
      "lastActivity": "2025-01-15T00:00:00.000Z",
      "linkedUsers": 15,
      "monthlySpend": 5000,
      "name": "Acme Inc",
      "object": "company",
      "plan": "enterprise",
      "updatedAt": "2025-01-10T15:30:00.000Z",
      "website": "https://acme.com",
      "customFields": {
        "location": "bar",
        "priority": "bar"
      }
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
  "object": "list",
  "totalCount": 42,
  "totalCountCapped": false
}