# Sub-Organizations

Sub-organizations are the core unit of the Bullseye partner program. Each sub-organization represents one of your clients and has its own visitor data, tracking pixel, ICP configurations, and credit allocation.

## What Are Sub-Organizations?

As a whitelabel partner, you manage multiple client organizations under your partner account. Each sub-organization operates independently with:

* Its own **tracking pixel** and pixel API key
* Separate **visitor data** and identification history
* Independent **ICP configurations** for lead scoring
* Individual **credit allocations** from your credit pool
* Configurable **allowed referrer domains**

## Creating Sub-Organizations

Create organizations via the [Partner API](/partner-api/organizations.md):

```bash
curl -X POST https://api.app.bullseye.so/api/v1/partner/organizations \
  -H "X-Partner-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Organization",
    "externalId": "client-456",
    "tier": "paid",
    "billingPeriod": "monthly",
    "billingDayOfMonth": 1,
    "initialCredits": 1000,
    "productType": "B2B"
  }'
```

### Key Fields

| Field               | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `name`              | Display name for the organization (required)                             |
| `externalId`        | Your internal identifier for correlation with your systems (optional)    |
| `tier`              | `trial` (max 500 credits) or `paid` (full credits)                       |
| `billingPeriod`     | `monthly`, `quarterly`, or `annually`                                    |
| `billingDayOfMonth` | Day of month for billing cycle (1-28)                                    |
| `initialCredits`    | Starting credit allocation                                               |
| `productType`       | `B2B` (company/employee identification) or `B2C` (person identification) |

## Organization Tiers

Sub-organizations operate in one of two tiers:

### Trial

* Limited to **500 credits** maximum
* Intended for evaluation and onboarding new clients
* Full platform functionality available

### Paid

* Full credit allocation with no cap
* Billing period and credit renewal apply
* Upgrade from trial at any time

Change tiers via the API:

```bash
curl -X PUT https://api.app.bullseye.so/api/v1/partner/organizations/{organizationId}/tier \
  -H "X-Partner-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier": "paid"}'
```

## Status Management

Control whether an organization is active or disabled:

* **Enabled** -- Organization is fully operational, the tracking pixel identifies visitors
* **Disabled** -- Organization is inactive, the tracking script returns an empty response

```bash
curl -X PUT https://api.app.bullseye.so/api/v1/partner/organizations/{organizationId}/status \
  -H "X-Partner-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

> **Note:** Disabling an organization does not delete any data. All visitor data and configurations are preserved and the organization can be re-enabled at any time.

## External IDs

Use the `externalId` field to map sub-organizations to your own internal system:

* Provide `externalId` when creating the organization
* It is stored in the organization's `partnerMetadata` field
* Use the `externalId` query parameter on `GET /partner/organizations` to look up organizations by your ID

```bash
curl "https://api.app.bullseye.so/api/v1/partner/organizations?externalId=client-456" \
  -H "X-Partner-API-Key: YOUR_API_KEY"
```

## Pixel Configuration

Each organization has its own tracking pixel. Retrieve the pixel configuration to get the script tag for installation:

```bash
curl https://api.app.bullseye.so/api/v1/partner/organizations/{organizationId}/pixel \
  -H "X-Partner-API-Key: YOUR_API_KEY"
```

The response includes:

| Field              | Description                             |
| ------------------ | --------------------------------------- |
| `apiKey`           | The pixel API key for this organization |
| `allowedReferrers` | List of allowed referrer domains        |
| `scriptTag`        | Ready-to-use HTML script tag            |

### Configuring Allowed Referrers

Restrict which domains the pixel will operate on:

```bash
curl -X PUT https://api.app.bullseye.so/api/v1/partner/organizations/{organizationId}/pixel \
  -H "X-Partner-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowedReferrers": ["example.com", "www.example.com"]}'
```

## Listing Visitors

Retrieve identified visitors for a sub-organization:

```bash
curl "https://api.app.bullseye.so/api/v1/partner/organizations/{organizationId}/visitors?page=1&limit=50" \
  -H "X-Partner-API-Key: YOUR_API_KEY"
```

The response includes visitor details with company information, ICP match status, engagement metrics, and page statistics.

## Deleting Organizations

Delete (soft delete) a sub-organization:

```bash
curl -X DELETE https://api.app.bullseye.so/api/v1/partner/organizations/{organizationId} \
  -H "X-Partner-API-Key: YOUR_API_KEY"
```

> **Warning:** This disables the organization. All visitor data and configurations are preserved but the organization will no longer be active.


---

# 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/partner-program/sub-organizations.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.