Visitors

The visitor tracking endpoints let you retrieve pixel configuration, installation scripts, individual visitor profiles, and initiate phone number searches.

Endpoints

Contact Count

The contact count endpoint is used to get the number of contacts matching a filter. It accepts company and contact filter criteria in the request body.

Method: POST
Path: /contacts/count

Request Body

Response Body

Example

curl -X POST "https://api.app.bullseye.so/api/v1/contacts/count" 
  -H "X-API-Key: bsk_live_your_api_key_here" 
  -H "Content-Type: application/json" 
  -d '{"company": {"industries": ["Technology"]}, "contact": {"job_titles": ["VP Marketing"]}}'

Get Pixel Configuration

Returns the pixel configuration for an organization, including API key, allowed referrers, verified domains, and script tag information.

Method: GET
Path: /visitor-tracking/\{organization_id\}

Path Parameters

Response Body

Returns a pixelConfig object with fields such as id, organizationId, allowedReferrers, verifiedDomains, and related ICP settings.

Example

curl -X GET "https://api.app.bullseye.so/api/v1/visitor-tracking/org_abc123" 
  -H "X-API-Key: bsk_live_your_api_key_here" 
  -H "Content-Type: application/json"

Update Pixel Configuration

Updates the pixel configuration for an organization.

Method: PUT
Path: /visitor-tracking/\{organization_id\}/pixel-config

Path Parameters

Request Body

JSON object with the fields to update (e.g., allowedReferrers, verifiedDomains).

Response Body

Returns the updated pixelConfig object.

Example

curl -X PUT "https://api.app.bullseye.so/api/v1/visitor-tracking/org_abc123/pixel-config" 
  -H "X-API-Key: bsk_live_your_api_key_here" 
  -H "Content-Type: application/json" 
  -d '{"allowedReferrers": ["https://example.com"], "verifiedDomains": ["example.com"]}'

Get Installation Script

Returns the installation script for embedding the Bullseye tracking pixel on your website.

Method: GET
Path: /visitor-tracking/\{organization_id\}/installation/script/\{type\}

Path Parameters

Response Body

Returns a script string containing the JavaScript snippet to embed.

Example

curl -X GET "https://api.app.bullseye.so/api/v1/visitor-tracking/org_abc123/installation/script/jsSnippet" 
  -H "X-API-Key: bsk_live_your_api_key_here" 
  -H "Content-Type: application/json"

Get Individual Visitor Details

Returns detailed profile information for a single identified visitor.

Method: GET
Path: /visitor-tracking/\{organization_id\}/visitors/\{visitor_id\}

Path Parameters

Response Body

Returns visitor profile data including contact information, company association, sessions[] (visit history), and pageview history.

When the organization has unlocked phone access for a visitor, the response also includes phoneNumber and phoneNumberSearchStatus (not_started, ongoing, found, not_found, or error).

Session objects (sessions[])

Each entry in sessions represents one visit. Network and geo fields use camelCase in the REST API (webhook payloads use snake_case for the same values).

Other session fields include landingPage, entryPage, exitPage, referrer, UTM parameters, device/browser metadata, sessionDurationSeconds, pageViewCount, and trackingParams.

Example

curl -X GET "https://api.app.bullseye.so/api/v1/visitor-tracking/org_abc123/visitors/vis_xyz789" 
  -H "X-API-Key: bsk_live_your_api_key_here" 
  -H "Content-Type: application/json"

Phone Number Search

Initiates an asynchronous phone number search for an identified visitor.

Availability: B2B organizations only (plus_employee product type). Requires the visitor to have a LinkedIn URL.

Billing: 5 identification credits only when a phone is found. not_found and expired searches are not charged. After not_found, re-initiate is rejected (no retry). After error / expired, one retry is allowed.

Method: POST
Path: /visitor-tracking/phone-number-search

Request Body

Response Body

Error codes

Getting results

• Poll GET /visitor-tracking/\{organizationId\}/visitors/\{visitorId\} - phoneNumber is returned only after the org has unlocked access
• Or subscribe to the visitor.phone_revealed webhook (same payload shape as visitor.identified, with visitor.phone populated)

Example

curl -X POST "https://api.app.bullseye.so/api/v1/visitor-tracking/phone-number-search" 
  -H "X-API-Key: bsk_live_your_api_key_here" 
  -H "Content-Type: application/json" 
  -d '{"organizationId": "org_abc123", "visitorId": "vis_xyz789"}'