Organizations

Manage organizations (sub-accounts) under your partner account. Create, update, and configure organizations, pixel settings, and retrieve visitor data.

List Organizations

List organizations with pagination and filtering.

Request:

GET /partner/organizations

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`pageSize`	integer	Items per page (default: 20)
`status`	string	Filter by status: `active`, `canceled`, `suspended`
`search`	string	Search by organization name
`externalId`	string	Filter by external ID

Response:

{
  "organizations": [
    {
      "id": "uuid",
      "name": "Acme Corp",
      "externalId": "acme-123",
      "status": "active",
      "tier": "paid",
      "credits": 1000,
      "metadata": {},
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20
}

Example:

curl -X GET "https://api.app.bullseye.so/api/v1/partner/organizations?page=1&pageSize=20&status=active" 
  -H "X-Partner-API-Key: your-api-key"

Create Organization

Create a new organization under the partner account.

Request:

POST /partner/organizations

Body:

{
  "name": "Acme Corp",
  "externalId": "acme-123",
  "ownerUserId": "user-uuid",
  "initialCredits": 500,
  "metadata": {"source": "signup"},
  "tier": "trial",
  "billingPeriod": "monthly",
  "billingDayOfMonth": 1,
  "productType": "B2B"
}

Field	Type	Required	Description
`name`	string	Yes	Organization display name
`externalId`	string	No	Your external reference ID
`ownerUserId`	string	No	User ID for the organization owner
`initialCredits`	integer	No	Initial credit allocation
`metadata`	object	No	Custom key-value metadata
`tier`	string	No	`trial` or `paid` (default: trial)
`billingPeriod`	string	No	`monthly` or `annual`
`billingDayOfMonth`	integer	No	Day of month for billing (1-28)
`productType`	string	No	`B2B` or `B2C`

Response:

{
  "organization": {
    "id": "uuid",
    "name": "Acme Corp",
    "externalId": "acme-123",
    "status": "active",
    "tier": "trial",
    "credits": 500,
    "metadata": {"source": "signup"},
    "createdAt": "2025-02-27T10:30:00Z"
  }
}

Example:

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": "Acme Corp", "externalId": "acme-123", "tier": "trial"}'

Get Organization

Retrieve a single organization by ID.

Request:

GET /partner/organizations/{organizationId}

Response:

{
  "organization": {
    "id": "uuid",
    "name": "Acme Corp",
    "externalId": "acme-123",
    "status": "active",
    "tier": "paid",
    "credits": 1000,
    "metadata": {},
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-02-27T09:00:00Z"
  }
}

Update Organization

Update organization details.

Request:

PUT /partner/organizations/{organizationId}

Body:

{
  "name": "Acme Corporation",
  "metadata": {"plan": "enterprise"},
  "credits": 1500
}

All fields are optional.

Response:

{
  "organization": {
    "id": "uuid",
    "name": "Acme Corporation",
    "metadata": {"plan": "enterprise"},
    "credits": 1500
  }
}

Delete Organization

Soft delete or disable an organization.

Request:

DELETE /partner/organizations/{organizationId}

Response: 204 No Content

Update Organization Status

Enable or disable an organization.

Request:

PUT /partner/organizations/{organizationId}/status

Body:

{
  "enabled": true
}

Response:

{
  "organization": {
    "id": "uuid",
    "status": "active"
  }
}

Update Organization Tier

Change the organization tier between trial and paid.

Request:

PUT /partner/organizations/{organizationId}/tier

Body:

{
  "tier": "paid"
}

Valid values: trial, paid

Response:

{
  "organization": {
    "id": "uuid",
    "tier": "paid"
  }
}

Update Organization Billing

Update billing configuration for an organization.

Request:

PUT /partner/organizations/{organizationId}/billing

Body:

{
  "billingPeriod": "monthly",
  "billingDayOfMonth": 15,
  "creditAllowance": 2000
}

All fields are optional.

Response:

{
  "organization": {
    "id": "uuid",
    "billingPeriod": "monthly",
    "billingDayOfMonth": 15,
    "creditAllowance": 2000
  }
}

Get Pixel Config

Retrieve the tracking pixel configuration for an organization.

Request:

GET /partner/organizations/{organizationId}/pixel

Response:

{
  "apiKey": "pixel-api-key",
  "allowedReferrers": ["https://acme.com", "https://*.acme.com"],
  "scriptTag": "<script src=\"https://track.example.com/script.js\" data-key=\"pixel-api-key\"></script>"
}

Update Pixel Config

Update allowed referrers for the tracking pixel.

Request:

PUT /partner/organizations/{organizationId}/pixel

Body:

{
  "allowedReferrers": ["https://acme.com", "https://app.acme.com", "https://*.acme.com"]
}

Response:

{
  "allowedReferrers": ["https://acme.com", "https://app.acme.com", "https://*.acme.com"]
}

List Visitors

List visitors for an organization with pagination.

Request:

GET /partner/organizations/{organizationId}/visitors

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)

Response:

{
  "visitorsCount": 150,
  "currentPage": 1,
  "totalPageCount": 8,
  "visitorStatistics": [
    {
      "visitorId": "uuid",
      "email": "john@acme.com",
      "firstName": "John",
      "lastName": "Doe",
      "companyName": "Acme Inc",
      "lastSeenAt": "2025-02-27T10:00:00Z"
    }
  ]
}

Example:

curl -X GET "https://api.app.bullseye.so/api/v1/partner/organizations/org-uuid/visitors?page=1&limit=20" 
  -H "X-Partner-API-Key: your-api-key"

Visitor statistics include phoneNumber (only when unlocked for the org) and phoneNumberSearchStatus (not_started | ongoing | found | not_found | error).

Initiate Phone Number Search

Starts a phone number enrichment for an identified visitor.

Availability: B2B (plus_employee) only. Visitor must have a LinkedIn URL.

Billing: 5 identification credits only when found. not_found is free and cannot be retried. Retry allowed after error.

Request:

POST /partner/organizations/{organizationId}/visitors/{visitorId}/phone-number-search

Response:

{
  "phoneNumberSearchStatus": "ongoing",
  "visitorId": "uuid"
}

Poll GET .../visitors or listen for visitor.phone_revealed on the identification webhook.

Example:

curl -X POST "https://api.app.bullseye.so/api/v1/partner/organizations/org-uuid/visitors/visitor-uuid/phone-number-search" 
  -H "X-Partner-API-Key: your-api-key"

Agency API (sub-organizations)

Agency accounts can initiate the same search for a sub-organization visitor:

POST /agency/{agencyOrganizationId}/organizations/{subOrgId}/visitors/{visitorId}/phone-number-search

Same B2B gate, billing, and response shape as the partner endpoint above. Requires agency write scope.