# ICP Configs

Ideal Customer Profile (ICP) configs define segmentation rules that filter and prioritize visitors. Create, update, and manage ICP configs for each organization.

## Segmentation Rule Structure

ICP configs use a rule structure with groups and conditions:

```json
{
  "groups": [
    {
      "operator": "AND",
      "conditions": [
        {
          "type": "industry",
          "comparator": "in",
          "value": ["Technology", "SaaS"],
          "optional": false
        },
        {
          "type": "company_size",
          "comparator": "gte",
          "value": 50,
          "optional": false
        }
      ]
    }
  ]
}
```

* **groups**: Array of condition groups. Groups are combined with OR (any group can match).
* **operator**: `AND` or `OR` - how conditions within a group are combined.
* **conditions**: Array of rule conditions.
* **optional**: If true, the condition does not exclude visitors but may affect scoring.

## Condition Types

| Type                  | Description            | Example Values                  |
| --------------------- | ---------------------- | ------------------------------- |
| `utm_source`          | UTM source parameter   | "google", "linkedin"            |
| `utm_medium`          | UTM medium parameter   | "cpc", "email"                  |
| `utm_campaign`        | UTM campaign parameter | "summer\_sale"                  |
| `utm_term`            | UTM term parameter     | "visitor identification"        |
| `utm_content`         | UTM content parameter  | "banner\_a"                     |
| `page_contains`       | Page URL contains      | "/pricing"                      |
| `page_equals`         | Page URL equals        | "<https://example.com/contact>" |
| `page_view_count`     | Number of page views   | 5                               |
| `session_count`       | Number of sessions     | 3                               |
| `industry`            | Company industry       | "Technology"                    |
| `company_size`        | Company employee count | 100                             |
| `icp_match`           | ICP match status       | true/false                      |
| `icp_score`           | ICP score value        | 0-100                           |
| `country`             | Visitor country        | "US"                            |
| `region`              | Visitor region/state   | "California"                    |
| `city`                | Visitor city           | "San Francisco"                 |
| `last_seen_days`      | Days since last visit  | 7                               |
| `persona_match`       | Persona match status   | true/false                      |
| `domain`              | Company domain         | "acme.com"                      |
| `job_title`           | Job title              | "CTO"                           |
| `linkedin_url`        | LinkedIn profile URL   | "<https://linkedin.com/>..."    |
| `employee_size_range` | Employee count range   | "51-200"                        |
| `company_city`        | Company city           | "Austin"                        |
| `company_region`      | Company region         | "Texas"                         |
| `company_postal_code` | Company postal code    | "78701"                         |

## Comparators

| Comparator     | Description               | Use With         |
| -------------- | ------------------------- | ---------------- |
| `equals`       | Exact match               | Strings, numbers |
| `not_equals`   | Does not equal            | Strings, numbers |
| `contains`     | String contains           | Strings          |
| `not_contains` | String does not contain   | Strings          |
| `starts_with`  | String starts with        | Strings          |
| `ends_with`    | String ends with          | Strings          |
| `gt`           | Greater than              | Numbers          |
| `gte`          | Greater than or equal     | Numbers          |
| `lt`           | Less than                 | Numbers          |
| `lte`          | Less than or equal        | Numbers          |
| `in`           | Value in list             | Arrays           |
| `not_in`       | Value not in list         | Arrays           |
| `between`      | Value between (inclusive) | \[min, max]      |
| `has_any`      | Has any of values         | Arrays           |
| `has_all`      | Has all values            | Arrays           |
| `exists`       | Field exists              | Booleans         |
| `not_exists`   | Field does not exist      | Booleans         |

***

## List ICP Configs

List all ICP configs for an organization.

**Request:**

```
GET /partner/organizations/{organizationId}/icp-configs
```

**Response:**

```json
{
  "icpConfigs": [
    {
      "id": "uuid",
      "slug": "enterprise-leads",
      "label": "Enterprise Leads",
      "rules": { "groups": [...] },
      "priority": 1,
      "isActive": true,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}
```

***

## Create ICP Config

Create a new ICP config.

**Request:**

```
POST /partner/organizations/{organizationId}/icp-configs
```

**Body:**

```json
{
  "label": "Enterprise Leads",
  "rules": {
    "groups": [
      {
        "operator": "AND",
        "conditions": [
          {
            "type": "industry",
            "comparator": "in",
            "value": ["Technology", "SaaS"],
            "optional": false
          },
          {
            "type": "company_size",
            "comparator": "gte",
            "value": 100,
            "optional": false
          }
        ]
      }
    ]
  },
  "priority": 1,
  "isActive": true
}
```

| Field      | Type    | Required | Description                                  |
| ---------- | ------- | -------- | -------------------------------------------- |
| `label`    | string  | Yes      | Display name for the config                  |
| `rules`    | object  | Yes      | Rule structure with groups and conditions    |
| `priority` | integer | No       | Sort order (lower = higher priority)         |
| `isActive` | boolean | No       | Whether the config is active (default: true) |

**Response:**

```json
{
  "icpConfig": {
    "id": "uuid",
    "slug": "enterprise-leads",
    "label": "Enterprise Leads",
    "rules": { "groups": [...] },
    "priority": 1,
    "isActive": true,
    "createdAt": "2025-02-27T10:30:00Z"
  }
}
```

**Example:**

```bash
curl -X POST "https://api.app.bullseye.so/api/v1/partner/organizations/org-uuid/icp-configs" \
  -H "X-Partner-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"label": "Enterprise Leads", "rules": {"groups": [{"operator": "AND", "conditions": [{"type": "industry", "comparator": "in", "value": ["Technology"]}]}]}}'
```

***

## Get ICP Config

Retrieve a single ICP config by slug.

**Request:**

```
GET /partner/organizations/{organizationId}/icp-configs/{slug}
```

**Response:**

```json
{
  "icpConfig": {
    "id": "uuid",
    "slug": "enterprise-leads",
    "label": "Enterprise Leads",
    "rules": { "groups": [...] },
    "priority": 1,
    "isActive": true,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-02-27T09:00:00Z"
  }
}
```

***

## Update ICP Config

Update an existing ICP config.

**Request:**

```
PUT /partner/organizations/{organizationId}/icp-configs/{slug}
```

**Body:**

```json
{
  "label": "Enterprise & Mid-Market Leads",
  "rules": { "groups": [...] },
  "priority": 2,
  "isActive": true
}
```

All fields are optional.

**Response:**

```json
{
  "icpConfig": {
    "id": "uuid",
    "slug": "enterprise-leads",
    "label": "Enterprise & Mid-Market Leads",
    "rules": { "groups": [...] },
    "priority": 2,
    "isActive": true
  }
}
```

***

## Delete ICP Config

Delete an ICP config.

**Request:**

```
DELETE /partner/organizations/{organizationId}/icp-configs/{slug}
```

**Response:** `204 No Content`

***

## Get ICP Stats

Retrieve ICP statistics for an organization over a date range.

**Request:**

```
GET /partner/organizations/{organizationId}/icp-configs/stats
```

**Query Parameters:**

| Parameter | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| `from`    | string | Start date (ISO 8601 or YYYY-MM-DD) |
| `to`      | string | End date (ISO 8601 or YYYY-MM-DD)   |

**Response:**

```json
{
  "stats": {
    "totalMatches": 150,
    "byConfig": [
      {
        "slug": "enterprise-leads",
        "label": "Enterprise Leads",
        "matches": 85
      }
    ],
    "from": "2025-02-01",
    "to": "2025-02-27"
  }
}
```

**Example:**

```bash
curl -X GET "https://api.app.bullseye.so/api/v1/partner/organizations/org-uuid/icp-configs/stats?from=2025-02-01&to=2025-02-27" \
  -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/icp-configs.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.