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:

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:

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

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

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:

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:

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:

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:

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.

Getting Started Credit Management