> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1eye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Exclusions

Manage Exclusions programmatically using the 1eye API. Create, retrieve, update, and delete Exclusions to prevent specific companies from being treated as eligible prospects.

Exclusions are part of the 1eye Knowledge Base. They help ensure that companies you do not want to target, such as existing customers, partners, internal organizations, or other excluded accounts, are filtered out during Buyer qualification and downstream activation.

Changes made through the API are reflected in the 1eye Console, and vice versa.

## Base URL

All Exclusion API requests use:

```text theme={null}
https://api.1eye.ai/v1/kb/exclusions
```

## Authentication

All endpoints require a valid 1eye API key.

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

API keys are scoped to a single workspace. All operations automatically apply to the workspace associated with your API key.

You do not need to provide a workspace ID.

The examples below use `$API_KEY` as the environment variable containing your API key.

For more information, see [Authentication](/api-reference/auth).

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/kb/exclusions` | List Exclusions |
| `GET` | `/v1/kb/exclusions/{id}` | Retrieve an Exclusion |
| `POST` | `/v1/kb/exclusions` | Create an Exclusion |
| `PATCH` | `/v1/kb/exclusions/{id}` | Update an Exclusion |
| `DELETE` | `/v1/kb/exclusions/{id}` | Delete an Exclusion |

All endpoints return JSON responses, except DELETE, which returns no response body.

***

## Exclusion Object

An Exclusion represents a company that should not be treated as an eligible target for your business.

For example, Snowbricks, a fictional cloud data and AI platform, might exclude its own organization to prevent internal company activity from being qualified as an external sales opportunity.

Other common exclusions include existing customers, partners, investors, and companies that should not enter your GTM workflows.

### Fields

| Field | Type | Description |
| - | - | - |
| `name` | string | Excluded company name |
| `short_name` | string | Unique short identifier |
| `domain` | string | Company website domain |
| `linkedin` | string | LinkedIn company page URL |
| `logo` | string | Company logo URL |
| `description` | string | Explanation of why the company is excluded |

`linkedin` and `logo` are optional when creating an Exclusion.

### Example Exclusion

```json theme={null}
{
  "name": "Snowbricks",
  "short_name": "snowbricks",
  "domain": "snowbricks.io",
  "linkedin": null,
  "logo": null,
  "description": "Snowbricks is the workspace's own organization. Exclude the company from Buyer qualification and targeting to prevent internal company activity from being treated as external purchase intent or entering sales and marketing activation workflows."
}
```

### System-Managed Fields

1eye automatically generates and maintains additional fields.

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique Exclusion identifier |
| `client_id` | string | Workspace identifier |
| `created_by` | object | Information about who created the Exclusion |
| `created_at` | datetime | Creation timestamp |
| `updated_at` | datetime | Last modification timestamp |

These fields are read-only.

***

## 1. List Exclusions

`GET /v1/kb/exclusions`

Retrieve a paginated list of excluded companies configured in your workspace.

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | integer | No | Maximum records to return. Default: 100. Maximum: 1,000 |
| `cursor` | string | No | Pagination cursor |

### Example Request

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/exclusions?limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

### Example Response

**200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "<exclusion_id>",
      "client_id": "wor_123456789012345678",
      "name": "Snowbricks",
      "short_name": "snowbricks",
      "domain": "snowbricks.io",
      "linkedin": null,
      "logo": null,
      "description": "Snowbricks is the workspace's own organization. Exclude the company from Buyer qualification and targeting to prevent internal company activity from being treated as external purchase intent or entering sales and marketing activation workflows.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

### Pagination

When additional results are available, use `pagination.next_cursor` to retrieve the next page.

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/exclusions?limit=100&cursor=YOUR_CURSOR" \
  -H "Authorization: Bearer $API_KEY"
```

When `next_cursor` is `null`, there are no additional results.

See [Pagination](/api-reference/pagination).

### Behavior

* Returns Exclusions belonging to the authenticated workspace.
* Excludes deleted records.
* Supports cursor-based pagination.
* Returns an empty `data` array when no exclusions exist.

***

## 2. Retrieve an Exclusion

`GET /v1/kb/exclusions/{id}`

Retrieve a specific Exclusion using its unique identifier.

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Exclusion identifier |

### Example Request

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/exclusions/$EXCLUSION_ID" \
  -H "Authorization: Bearer $API_KEY"
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<exclusion_id>",
  "client_id": "wor_123456789012345678",
  "name": "Snowbricks",
  "short_name": "snowbricks",
  "domain": "snowbricks.io",
  "linkedin": null,
  "logo": null,
  "description": "Snowbricks is the workspace's own organization. Exclude the company from Buyer qualification and targeting to prevent internal company activity from being treated as external purchase intent or entering sales and marketing activation workflows.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

* Returns the complete Exclusion record.
* Includes system-generated metadata.
* Returns `404 Not Found` if the Exclusion does not exist, has been deleted, or belongs to another workspace.

***

## 3. Create an Exclusion

`POST /v1/kb/exclusions`

Add a company to your workspace's Exclusions.

The excluded company will no longer be considered an eligible target during future Buyer qualification and matching.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Company name |
| `short_name` | string | Yes | Unique short identifier |
| `domain` | string | Yes | Company website domain |
| `linkedin` | string | No | LinkedIn company page URL |
| `logo` | string | No | Company logo URL |
| `description` | string | No | Reason for exclusion |

### Example Request

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/kb/exclusions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Snowbricks",
    "short_name": "snowbricks",
    "domain": "snowbricks.io"
  }'
```

### Example Response

**201 Created**

```json theme={null}
{
  "id": "<exclusion_id>",
  "client_id": "wor_123456789012345678",
  "name": "Snowbricks",
  "short_name": "snowbricks",
  "domain": "snowbricks.io",
  "linkedin": null,
  "logo": null,
  "description": "Snowbricks is the workspace's own organization. Exclude the company from Buyer qualification and targeting to prevent internal company activity from being treated as external purchase intent or entering sales and marketing activation workflows.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

When an Exclusion is created:

1. 1eye generates a unique Exclusion ID.
2. The company is associated with your workspace.
3. The Exclusion appears in the Knowledge Base.
4. The company becomes ineligible for future Buyer qualification and targeting.
5. The Exclusion can be retrieved or updated through the API.

**Important:** Creating an Exclusion does not permanently delete existing Buyers, Signals, or historical data.

### Validation

* `name` must not be empty.
* `short_name` must not be empty.
* `domain` must be valid.
* `description` must not be empty.
* `linkedin`, when supplied, must be a valid LinkedIn company URL.
* `logo`, when supplied, must be a valid image URL.
* `short_name` must be unique among active Exclusions in the workspace.
* System-managed fields cannot be supplied.

***

## 4. Update an Exclusion

`PATCH /v1/kb/exclusions/{id}`

Update an existing Exclusion.

Only supplied fields are modified.

### Request Body

| Field | Type | Required |
| - | - | - |
| `name` | string | No |
| `short_name` | string | No |
| `domain` | string | No |
| `linkedin` | string | No |
| `logo` | string | No |
| `description` | string | No |

At least one editable field must be supplied.

### Example Request

```bash theme={null}
curl -X PATCH "https://api.1eye.ai/v1/kb/exclusions/$EXCLUSION_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Snowbricks is the workspace owner and must be excluded from prospect qualification, Buyer targeting, Target Lists, and future GTM activation. Activity associated with the Snowbricks company should not be treated as an external sales opportunity."
  }'
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<exclusion_id>",
  "client_id": "wor_123456789012345678",
  "name": "Snowbricks",
  "short_name": "snowbricks",
  "domain": "snowbricks.io",
  "linkedin": null,
  "logo": null,
  "description": "Snowbricks is the workspace owner and must be excluded from prospect qualification, Buyer targeting, Target Lists, and future GTM activation. Activity associated with the Snowbricks company should not be treated as an external sales opportunity.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}
```

### Behavior

* Supports partial updates.
* Preserves omitted fields.
* Preserves the original Exclusion ID.
* Reflects changes in the Console.
* Uses updated exclusion information for future processing.

**Important:** Updating an Exclusion does not automatically trigger historical Buyer reevaluation.

***

## 5. Delete an Exclusion

`DELETE /v1/kb/exclusions/{id}`

Remove a company from your workspace's active Exclusions.

Deletion performs a **soft delete** of the Exclusion record.

### Example Request

```bash theme={null}
curl -X DELETE "https://api.1eye.ai/v1/kb/exclusions/$EXCLUSION_ID" \
  -H "Authorization: Bearer $API_KEY"
```

### Response

**204 No Content**

The response body is empty.

### What Happens When an Exclusion Is Deleted?

* The Exclusion is removed from the active Knowledge Base.
* It no longer appears in List Exclusions.
* Retrieving the deleted Exclusion returns `404 Not Found`.
* The company is no longer excluded by that configuration.
* The company may become eligible for future Buyer qualification, subject to other targeting rules.
* Historical company information and Signals remain preserved.

**Important:** Removing an Exclusion does not automatically reevaluate previously excluded Buyers or restore them to active Target Lists.

Eligibility is determined during subsequent processing.

**Restoring deleted Exclusions is not currently exposed through the public API.**

***

## 6. How Exclusions Affect Buyer Intelligence

Exclusions help prevent unwanted companies from entering your active go-to-market workflows.

For example, Snowbricks might exclude:

| Company Category | Reason |
| - | - |
| Internal Organization | Avoid treating internal activity as external buying intent |
| Existing Customers | Avoid unnecessary new-customer prospecting |
| Existing Partners | Prevent partner accounts from entering prospecting workflows |
| Investors | Avoid targeting investor organizations |
| Other Restricted Accounts | Respect internal targeting decisions |

### Exclusion Matching

1eye uses the configured company information to identify companies that should be excluded.

The company domain provides a primary matching identifier, while additional company information may support identification.

### REEM Integration

Exclusions are applied during relevant Buyer evaluation and matching.

**Resolve → Enrich → Evaluate → Match**

When a company matches an active Exclusion, it should not be treated as an eligible target.

### Impact of Exclusion Changes

| Operation | Impact |
| - | - |
| Create | Company becomes excluded from future qualification |
| Update | Updated exclusion information is used for future processing |
| Delete | Exclusion rule is removed from future processing |

### Existing Data

Exclusions do not permanently delete historical data.

Existing Buyers and Signals remain available according to their normal access and visibility rules.

Previously synchronized CRM contacts are not automatically deleted when an Exclusion is created.

***

## 7. Exclusions vs. Competitors

Competitors and Exclusions use the same company information fields but serve different purposes.

| Resource | Purpose |
| - | - |
| Competitors | Monitor relevant competitive activity |
| Exclusions | Prevent companies from qualifying as targets |

A Competitor is not automatically an Exclusion.

For example, Snowbricks may monitor Databricks-related research as a buying signal without automatically excluding Databricks from every applicable workflow.

If a company should also be excluded from targeting, add it separately to Exclusions.

***

## 8. Flat Exclusion Management

Exclusions are managed as individual company records.

You do not need to create an Exclusion List before adding companies.

Each excluded company has its own resource identifier and can be managed directly through:

```text theme={null}
GET    /v1/kb/exclusions
GET    /v1/kb/exclusions/{id}
POST   /v1/kb/exclusions
PATCH  /v1/kb/exclusions/{id}
DELETE /v1/kb/exclusions/{id}
```

This provides a consistent experience with other Knowledge Base resources.

**One company, one Exclusion record, one simple CRUD interface.**

***

## 9. Error Handling

All Exclusion endpoints use the standard 1eye API error format.

| HTTP Status | Description |
| - | - |
| `200` | Successful retrieval or update |
| `201` | Exclusion created |
| `204` | Exclusion deleted |
| `400` | Invalid request |
| `401` | Invalid or missing API key |
| `403` | Insufficient permissions |
| `404` | Exclusion not found or inaccessible |
| `409` | Duplicate or conflicting Exclusion |
| `429` | Workspace rate limit exceeded |
| `500` | Internal server error |

### Example Error

**404 Not Found**

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Exclusion not found.",
    "request_id": "req_359051753366339585"
  }
}
```

See [Errors](/api-reference/errors).

***

## 10. Pagination & Rate Limits

List Exclusions supports cursor-based pagination.

* Default page size: 100.
* Maximum page size: 1,000.
* Use `cursor` for subsequent pages.
* `next_cursor: null` indicates the end of the collection.

Exclusion API requests count toward your workspace API rate limits.

See [Pagination](/api-reference/pagination) and [Rate Limits](/api-reference/rate-limits).

***

## 11. Best Practices

### Exclude Companies Intentionally

Use Exclusions for companies that should not enter your active targeting workflows.

Examples include existing customers, partners, investors, and internal organizations.

### Use Accurate Company Domains

Domains help 1eye identify the intended company.

Avoid incorrect or overly broad domains that could exclude unrelated organizations.

### Write Clear Exclusion Reasons

Descriptions should explain why a company should not be targeted.

Examples:

```text theme={null}
Existing enterprise customer.
Current technology integration partner.
Investor organization.
Internal company domain.
Account excluded by sales operations.
```

### Avoid Unnecessary Exclusions

Only exclude companies when there is a clear business reason.

Overly broad exclusions can reduce the number of relevant Buyers available to your GTM team.

### Review Exclusions Regularly

Revisit Exclusions when customer, partner, or account relationships change.

### Delete Carefully

Deleting an Exclusion makes the company eligible for future evaluation unless another rule excludes it.

Previously excluded Buyers are not automatically reevaluated.

***

## 12. Related Documentation

* [Authentication](/api-reference/auth)
* [Pagination](/api-reference/pagination)
* [Errors](/api-reference/errors)
* [Rate Limits](/api-reference/rate-limits)
* [List Buyers](/api-reference/list-buyers)
* [Knowledge Base – Exclusions](/knowledge-base/exclusions)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.