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.