# 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:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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:**

```json
{
  "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:**

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

***

## Get Organization

Retrieve a single organization by ID.

**Request:**

```
GET /partner/organizations/{organizationId}
```

**Response:**

```json
{
  "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:**

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

All fields are optional.

**Response:**

```json
{
  "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:**

```json
{
  "enabled": true
}
```

**Response:**

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

***

## Update Organization Tier

Change the organization tier between trial and paid.

**Request:**

```
PUT /partner/organizations/{organizationId}/tier
```

**Body:**

```json
{
  "tier": "paid"
}
```

Valid values: `trial`, `paid`

**Response:**

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

***

## Update Organization Billing

Update billing configuration for an organization.

**Request:**

```
PUT /partner/organizations/{organizationId}/billing
```

**Body:**

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

All fields are optional.

**Response:**

```json
{
  "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:**

```json
{
  "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:**

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

**Response:**

```json
{
  "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:**

```json
{
  "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:**

```bash
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"
```


---

# 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-api/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.