API Overview
The Bullseye REST API provides programmatic access to visitor identification data, companies, organizations, lists, ICP configurations, integrations, and billing. Use the API to build custom workflows, sync data with internal tools, or automate common operations.
Plan Requirement
Direct API access is available on Scale plans and above. If you are on Starter, Growth, or Free Trial, upgrade to Scale to use the API.
Base URL
All API requests use the following base URL:
https://api.app.bullseye.so/api/v1Authentication
Authenticate API requests using an Organization API Key. Include your key in the X-API-Key header:
X-API-Key: bsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCreate API keys in the Bullseye dashboard under Organization Settings > API Keys. See Authentication for full details on scopes, rate limiting, and security best practices.
Response Format
All responses are returned as JSON. Successful responses use standard HTTP status codes (200, 201, 202, 204). Error responses include a structured body with the following shape:
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code (e.g., organization_not_found) |
message | string | Human-readable error description |
details | object | Optional additional context |
Error Handling
| Status | Description |
|---|---|
| 400 | Bad Request – Invalid request parameters or body |
| 401 | Unauthorized – Missing or invalid API key |
| 404 | Not Found – Resource does not exist |
| 422 | Unprocessable Entity – Validation failed or business rule violated |
| 500 | Internal Server Error – Server-side error |
Pagination
Endpoints that return paginated data use the following query parameters:
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (1-based). Default: 1 |
limit | integer | Number of items per page. Default varies by endpoint |
Paginated responses typically include a data array and metadata such as total or page for constructing navigation.
Rate Limits
API key-authenticated requests are limited to 1,000 requests per minute per key. Rate limit information is included in response headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Remaining requests in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header. Implement exponential backoff when handling rate limit errors.
Endpoint Groups
| Section | Description |
|---|---|
| Authentication | API key authentication, scopes, and rate limiting |
| API Keys | Create, list, and revoke Organization API keys |
| Visitors | Visitor tracking config, individual visitor details, installation scripts, phone number search, contact count |
| Companies | Company statistics, company visitors, chart data, CSV download |
| Organizations | Create, list, get, update organizations; team members; max overages |
| Lists | Create, list, get, refresh, and delete saved lists |
| ICP Configs | Ideal Customer Profile configuration management |
| Integrations | Integration flows, token management, account selection |
| Payments | Subscription plans, checkout, update, cancel, customer portal |
| Webhooks | Event payloads, signature verification, retry behavior |