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": "[email protected]",
      "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"