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

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
sort_order	string	No	Sort direction: asc or desc (default: desc)
account_level	string	No	Filter by account level (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
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.leadvibe.com/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/{id} - Get account detail
• DELETE /accounts/batch - Delete multiple accounts
• GET /accounts/{accountId}/engagement-timeline - Get engagement timeline
• GET /account-scoring/rulesets - Manage account scoring rules

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