Accounts API

List accounts with their scores, levels, engagement metrics, and metadata. Accounts represent companies or organizations that group related leads, providing an account-level view of engagement and buying signals.

GET /accounts/by-domain

Look up an account by its domain or company name. Returns the first matching account, or an empty response if no match is found.

Query Parameters

Parameter	Type	Required	Description
domain	string	No	Domain to search for (e.g., acme.com). Checked first when both parameters are provided.
name	string	No	Exact company name to search for. Used as a fallback when domain is not provided or returns no match.

At least one of domain or name must be provided.

Response

200 OK

{
  "account_id": "acct_abc123",
  "name": "Acme Corporation",
  "domain": "acme.com"
}

Returns null when no matching account is found.

Field	Type	Description
account_id	string	Unique account identifier
name	string	Account name
domain	string	Primary email domain

Example

curl -X GET "https://api.kenbun.io/accounts/by-domain?domain=acme.com" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
400	Bad Request	Neither domain nor name was provided
401	Unauthorized	Check authentication credentials

---

GET /accounts/fuzzy

Search for accounts by name using fuzzy matching. Returns the top accounts whose names are similar to the provided query, ranked by similarity score. This is useful when you have a company name that may not exactly match an existing account -- for example, "Salesforce" vs. "Salesforce LLC" or "ACME Corp" vs. "Acme Corporation".

The endpoint uses a combination of string similarity algorithms to find close matches, returning up to 5 results above a 60% similarity threshold.

When to Use This

• Lead imports: When importing contacts from external sources (e.g., LinkedIn), use this to find existing accounts before creating duplicates
• Data deduplication: Check whether a company already exists under a slightly different name
• Account linking: Match imported company names against your account list to link leads to the right account

Query Parameters

Parameter	Type	Required	Description
name	string	Yes	Company name to search for (e.g., Salesforce LLC)

Response

200 OK

{
  "matches": [
    {
      "account_id": "acct_abc123",
      "name": "Salesforce",
      "score": 0.92
    },
    {
      "account_id": "acct_def456",
      "name": "Salesforce.com Inc",
      "score": 0.78
    }
  ]
}

Field	Type	Description
matches	array	List of matching accounts, sorted by similarity (highest first). Maximum 5 results.
matches[].account_id	string	Unique account identifier
matches[].name	string	Account name
matches[].score	number	Similarity score between 0 and 1 (higher is more similar)
capped	boolean	Present and true when the account set is too large for fuzzy search. An empty matches array is returned in this case.

Score interpretation:

Score Range	Meaning
0.90 -- 1.0	Very high confidence (near-exact match)
0.85 -- 0.89	High confidence (safe for automated linking)
0.70 -- 0.84	Moderate confidence (recommend user confirmation)
0.60 -- 0.69	Low confidence (possible match, needs review)

Example

curl -X GET "https://api.kenbun.io/accounts/fuzzy?name=Salesforce%20LLC" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
400	Bad Request	The name parameter is missing or empty
401	Unauthorized	Check authentication credentials
500	Server Error	Contact support if the issue persists

---

GET /accounts

Returns a paginated list of accounts for the active Organizational Unit, including firmographic scores, engagement metrics, and surge activity.

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search by account name or domain
page	integer	No	Page number for pagination (default: 1)
per_page	integer	No	Results per page (default: 25, max: 100)
sort_by	string	No	Field to sort by: name, score, engagement, last_activity, owner_name
sort_order	string	No	Sort direction: asc or desc (default: desc)
account_level	string	No	Filter by account level name (e.g., "Target", "Qualified")
min_score	integer	No	Minimum account score
max_score	integer	No	Maximum account score
min_engagement	integer	No	Minimum engagement score
owner_name	string	No	Filter by owner display name (partial match, case-insensitive)
has_leads	boolean	No	When true, returns only accounts that have at least one associated lead
created_after	string	No	ISO 8601 timestamp - accounts created after this date
created_before	string	No	ISO 8601 timestamp - accounts created before this date
last_activity_after	string	No	ISO 8601 timestamp - accounts active after this date
surge_status	boolean	No	Filter by surge activity: true (active surge) or false

Example

curl -X GET "https://api.kenbun.io/accounts?page=1&per_page=25&sort_by=score&account_level=Target" \
  -H "Authorization: Bearer <token>"

Response

200 OK

{
  "accounts": [
    {
      "account_id": "acct_abc123",
      "domain": "acme.com",
      "name": "Acme Corporation",
      "account_score": 85,
      "account_level": "Target",
      "total_leads": 12,
      "engagement_score": 245,
      "last_activity_at": "2026-01-30T14:23:00Z",
      "surge_active": true,
      "surge_window_start": "2026-01-28T00:00:00Z",
      "surge_event_count": 47,
      "metadata": {
        "company_size": "Enterprise",
        "industry": "Technology",
        "country": "United States",
        "employees": 2500,
        "plan": "Pro"
      },
      "created_at": "2025-11-15T10:00:00Z",
      "updated_at": "2026-01-30T14:23:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 142,
    "total_pages": 6
  }
}

Response Fields

Field	Type	Description
account_id	string	Unique account identifier
domain	string	Primary email domain for the account
name	string	Account name (company name)
account_score	integer	Firmographic score based on account attributes
account_level	string	Account tier (Target, Qualified, Standard, etc.)
total_leads	integer	Number of contacts associated with this account
engagement_score	integer	Combined engagement across all contacts
last_activity_at	timestamp	Most recent activity from any contact
surge_active	boolean	Whether account is currently experiencing surge
surge_window_start	timestamp	When the current surge window started (if active)
surge_event_count	integer	Number of events during current surge (if active)
metadata	object	Account metadata properties (firmographic data)
created_at	timestamp	When the account was first created
updated_at	timestamp	When the account was last modified

Pagination Object

Field	Type	Description
page	integer	Current page number
per_page	integer	Results per page
total_count	integer	Total number of accounts matching filters
total_pages	integer	Total number of pages available

Common Errors

Status	Meaning	Solution
400	Bad Request	Invalid query parameter value (e.g., invalid sort_by)
401	Unauthorized	Check authentication credentials
500	Server Error	Contact support if the issue persists

---

Notes

• Accounts are automatically created when leads with new account_id values are added
• Account scores are calculated based on Account Scoring Rules
• Account levels are assigned based on Account Level thresholds
• Surge detection is enabled at the organization level
• All accounts are scoped to your Organizational Unit

Related Endpoints

• GET /accounts/by-domain - Look up account by domain or name
• GET /accounts/fuzzy - Fuzzy search accounts by name similarity
• GET /accounts/{id} - Get account detail
• POST /accounts/{id}/merge - Merge a source account into a target account
• PATCH /accounts/{id}/metadata - Update account metadata
• Buying Committee - Manage buying committee members and roles

Related Documentation

• Account Management - User guide for working with accounts
• Account Scoring Rules - Configure firmographic scoring
• Account Levels - Set up account tiers
• ABM Overview - Understanding Account-Based Marketing