# Visitors

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

## Endpoints

| Method | Path                                                             | Description                    |
| ------ | ---------------------------------------------------------------- | ------------------------------ |
| GET    | `/visitor-tracking/{organization_id}`                            | Get pixel configuration        |
| PUT    | `/visitor-tracking/{organization_id}/pixel-config`               | Update pixel configuration     |
| GET    | `/visitor-tracking/{organization_id}/installation/script/{type}` | Get installation script        |
| GET    | `/visitor-tracking/{organization_id}/visitors/{visitor_id}`      | Get individual visitor details |
| POST   | `/visitor-tracking/phone-number-search`                          | Search for phone numbers       |
| POST   | `/contacts/count`                                                | Get contact count by filters   |

***

## 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

| Field     | Type   | Required | Description                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `company` | object | No       | Company filter (industries, sizes, domains, etc.)           |
| `contact` | object | No       | Contact filter (job titles, seniorities, departments, etc.) |

### Response Body

| Field   | Type    | Description                             |
| ------- | ------- | --------------------------------------- |
| `count` | integer | Number of contacts matching the filters |

### Example

```bash
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

| Parameter         | Type   | Description     |
| ----------------- | ------ | --------------- |
| `organization_id` | string | Organization ID |

### Response Body

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

### Example

```bash
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

| Parameter         | Type   | Description     |
| ----------------- | ------ | --------------- |
| `organization_id` | string | Organization ID |

### Request Body

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

### Response Body

Returns the updated `pixelConfig` object.

### Example

```bash
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

| Parameter         | Type   | Description                                            |
| ----------------- | ------ | ------------------------------------------------------ |
| `organization_id` | string | Organization ID                                        |
| `type`            | string | Script type: `jsSnippet` (standard), `googleTag` (GTM) |

### Response Body

Returns a `script` string containing the JavaScript snippet to embed.

### Example

```bash
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

| Parameter         | Type   | Description     |
| ----------------- | ------ | --------------- |
| `organization_id` | string | Organization ID |
| `visitor_id`      | string | Visitor ID      |

### Response Body

Returns visitor profile data including contact information, company association, session data, and pageview history.

### Example

```bash
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 a visitor. The search runs in the background; poll or use webhooks to receive results.

**Method:** POST\
**Path:** `/visitor-tracking/phone-number-search`

### Request Body

| Field            | Type   | Required | Description          |
| ---------------- | ------ | -------- | -------------------- |
| `organizationId` | string | Yes      | Organization ID      |
| `visitorId`      | string | Yes      | Visitor ID to search |

### Response Body

| Field                     | Type   | Description                                     |
| ------------------------- | ------ | ----------------------------------------------- |
| `phoneNumberSearchStatus` | object | Status of the search (e.g., pending, completed) |
| `visitorId`               | string | Visitor ID                                      |

### Example

```bash
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"}'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bullseye.so/api-reference/visitors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.