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

# Search Exclusions

> Suppress known people or companies from search results with inline IDs or reusable saved exclusion lists.

## Use case

Exclusions keep known records out of search results — existing customers, accounts your sales team is already working, seed profiles that shouldn't appear in lookalike results, or people and companies that should never be contacted.

The API searches first, then removes excluded records before returning results. Matching behavior is unchanged.

```mermaid theme={null}
flowchart LR
  A[Search matches candidates] --> B[Remove inline excluded IDs]
  B --> C[Remove saved-list members]
  C --> D[Return eligible rows]
```

## Errors

For error responses (400, 403, 422, etc.), see [Handling Errors](/api-reference/errors).

## Choosing an approach

| Need                                       | Use                                                                   |
| ------------------------------------------ | --------------------------------------------------------------------- |
| Exclude a few people in one request        | `exclude_entity_ids`                                                  |
| Exclude a few companies in one request     | `exclude_entity_ids`                                                  |
| Reuse a large suppression list             | `exclude_list_ids`                                                    |
| Build a saved list from IDs in the request | `POST /search/exclusion-lists` with `source.type = "entity_ids"`      |
| Build a saved list from a CSV upload       | `POST /search/exclusion-lists` with `source.type = "resource_handle"` |
| Build a saved list from a completed search | `POST /search/exclusion-lists` with `source.type = "search_id"`       |

## Supported endpoints

| Endpoint                                   | Supports exclusions? | Notes                                                                                                             |
| ------------------------------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `POST /search/query`                       | Yes                  | Primary paginated search endpoint. Send exclusions on the first request. Cursor requests must send only `cursor`. |
| `POST /search/start-deep-search`           | Yes                  | Deep search accepts the same exclusion fields. See [Deep search](#deep-search).                                   |
| `GET /search/status/{task_id}`             | N/A                  | Polls deep-search status. Completed responses include the `search_id` used for later `/search/query` browsing.    |
| `POST /search/exclusion-lists`             | Yes                  | Creates reusable saved exclusion lists.                                                                           |
| `GET /search/exclusion-lists`              | N/A                  | Lists saved exclusion lists for the organization.                                                                 |
| `GET /search/exclusion-lists/{list_id}`    | N/A                  | Gets status and size for one saved list.                                                                          |
| `DELETE /search/exclusion-lists/{list_id}` | N/A                  | Deletes a saved list.                                                                                             |

## Inline exclusions

Inline exclusions apply only to the request that sends them.

### People

Use `exclude_entity_ids`. In people mode it accepts LinkedIn public IDs or LinkedIn profile URLs:

```json theme={null}
{
  "mode": "people",
  "query": "VP Engineering in New York",
  "exclude_entity_ids": ["jane-doe", "https://linkedin.com/in/john-smith"]
}
```

### Companies

Company searches use `exclude_entity_ids`:

```json theme={null}
{
  "mode": "company",
  "simple_filters": {
    "hq_country_iso2": { "$eq": "US" }
  },
  "exclude_entity_ids": [
    "1441",
    "linkedin.com/company/openai",
    "stripe.com"
  ]
}
```

Company identifiers can be:

* Numeric LinkedIn company IDs
* LinkedIn company URLs
* LinkedIn company slugs
* Exact website domains

Identifiers that match no company (unresolvable) or more than one (ambiguous) are skipped.

## Saved exclusion lists

Saved lists are reusable, organization-scoped suppression lists. Each list has an `entity_type` of `person` or `company`; a person list can only be used in people search, and a company list only in company search.

Creating a list is asynchronous. A successful request returns `202 Accepted` with the list `id` and `status: "pending"`:

```json theme={null}
{
  "id": "11111111-1111-1111-1111-111111111111",
  "status": "pending"
}
```

Poll `GET /search/exclusion-lists/{list_id}` and use the list only after `status` is `ready`.

### Create from inline IDs

Use `source.type = "entity_ids"` for both people and companies.

People:

```json theme={null}
{
  "name": "Do not contact people",
  "entity_type": "person",
  "source": {
    "type": "entity_ids",
    "entity_ids": ["jane-doe", "https://linkedin.com/in/john-smith"]
  }
}
```

Companies:

```json theme={null}
{
  "name": "Customer accounts",
  "entity_type": "company",
  "source": {
    "type": "entity_ids",
    "entity_ids": ["1441", "linkedin.com/company/openai", "stripe.com"]
  }
}
```

### Create from a CSV upload

Upload the CSV first to get a `resource_handle_id`, then create the list:

```json theme={null}
{
  "name": "CSV suppression list",
  "entity_type": "company",
  "source": {
    "type": "resource_handle",
    "resource_handle_id": "8f14e45f-1111-2222-3333-abcdefabcdef",
    "id_column": "company_url"
  }
}
```

`id_column` is optional if the API can detect the right column. Recognized column names:

| `entity_type` | Recognized columns                                                                         |
| ------------- | ------------------------------------------------------------------------------------------ |
| `person`      | `public_id`, `publicId`, `linkedin_url`, `linkedinUrl`                                     |
| `company`     | `entity_id`, `company_id`, `companyId`, `linkedin_url`, `linkedinUrl`, `website`, `domain` |

### Create from a completed search

Use `source.type = "search_id"` to turn a completed search into a reusable list. The source search mode must match the list `entity_type`: a people search produces a `person` list, a company search a `company` list.

```json theme={null}
{
  "name": "Companies from last search",
  "entity_type": "company",
  "source": {
    "type": "search_id",
    "search_id": "22222222-2222-2222-2222-222222222222",
    "max_results": 5000
  }
}
```

The `source` can carry its own exclusions, so the list is built from the search results minus another list:

```json theme={null}
{
  "name": "Search results except current customers",
  "entity_type": "company",
  "source": {
    "type": "search_id",
    "search_id": "22222222-2222-2222-2222-222222222222",
    "max_results": 5000,
    "exclude_list_ids": ["11111111-1111-1111-1111-111111111111"]
  }
}
```

<Warning>
  `search_id` stores only the query — not any exclusions you applied when browsing the results. If the list should match what you previewed, send the same exclusions in the `source`.
</Warning>

## Using a saved list in search

Pass the list ID in `exclude_list_ids`:

```json theme={null}
{
  "mode": "company",
  "simple_filters": {
    "hq_country_iso2": { "$eq": "US" }
  },
  "exclude_list_ids": ["11111111-1111-1111-1111-111111111111"]
}
```

Saved lists and inline exclusions combine in the same request:

```json theme={null}
{
  "mode": "company",
  "simple_filters": {
    "hq_country_iso2": { "$eq": "US" }
  },
  "exclude_list_ids": ["11111111-1111-1111-1111-111111111111"],
  "exclude_entity_ids": ["stripe.com"]
}
```

## Limits

| Limit                                        | Value   |
| -------------------------------------------- | ------- |
| Saved lists per request (`exclude_list_ids`) | 5       |
| Inline IDs per request                       | 1,000   |
| IDs per `entity_ids` source                  | 10,000  |
| Members per saved list                       | 250,000 |

## Pagination

Send exclusions only on the first `/search/query` request. Cursor requests must send only `cursor` — no `exclude_*`, `mode`, `query`, or `page_size`.

First page:

```json theme={null}
{
  "mode": "people",
  "query": "Founders in San Francisco",
  "exclude_entity_ids": ["jane-doe"],
  "page_size": 25
}
```

Next page:

```json theme={null}
{
  "cursor": "eyJ..."
}
```

With exclusions, a page can contain fewer rows than `page_size` — even zero rows while `has_more` is still `true`. Keep paging until `next_cursor` is `null`.

<Note>
  Don't rely on `total_available` to size pagination or count how many records were excluded. Page until `next_cursor` is `null` to retrieve every eligible row.
</Note>

## Deep search

`POST /search/start-deep-search` accepts the same exclusion fields: `exclude_entity_ids` and `exclude_list_ids`.

```json theme={null}
{
  "query": "VP Engineering at Series B SaaS companies in New York",
  "mode": "people",
  "max_results": 500,
  "exclude_list_ids": ["11111111-1111-1111-1111-111111111111"],
  "exclude_entity_ids": ["jane-doe"]
}
```

For `output_mode: "csv"`, Sixtyfour applies exclusions before producing the CSV.

For `output_mode: "query_only"`, the returned `search_id` stores the query, not your exclusions — send them again when browsing:

1. Call `POST /search/start-deep-search` and save the returned `task_id`.
2. Poll `GET /search/status/{task_id}` until the search is `completed`.
3. Read `search_id` from the completed status response.
4. Call `POST /search/query` with that `search_id` and any exclusions to apply.

```json theme={null}
{
  "search_id": "22222222-2222-2222-2222-222222222222",
  "exclude_list_ids": ["11111111-1111-1111-1111-111111111111"],
  "exclude_entity_ids": ["jane-doe"]
}
```