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:
code
string
Machine-readable error code (e.g., organization_not_found)
message
string
Human-readable error description
details
object
Optional additional context
Error Handling
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:
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:
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
API key authentication, scopes, and rate limiting
Create, list, and revoke Organization API keys
Visitor tracking config, individual visitor details, installation scripts, phone number search, contact count
Company statistics, company visitors, chart data, CSV download
Create, list, get, update organizations; team members; max overages
Create, list, get, refresh, and delete saved lists
Ideal Customer Profile configuration management
Integration flows, token management, account selection
Subscription plans, checkout, update, cancel, customer portal
Event payloads, signature verification, retry behavior
Last updated