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

# Search Buyers

Search Buyers using structured filtering criteria with the 1eye API. Combine multiple conditions to find Buyers matching specific ICPs, Personas, company characteristics, contact attributes, and buying-intent indicators.

Search Buyers enables developers, GTM platforms, and AI agents to identify relevant Buyers without retrieving and filtering entire datasets.

The API searches existing Buyer Intelligence and returns the same Buyer objects available through the List Buyers API.

**Search Buyers is read-only.** Searches do not trigger enrichment, generate Signals, reevaluate Buyers, or consume additional 1eye credits.

## Base URL

All Search Buyers requests use:

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

## Authentication

All requests require a valid 1eye API key.

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

API keys are scoped to a single workspace. Searches automatically return Buyers belonging 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).

## Endpoint

| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/v1/buyers/search` | Search Buyers using structured filtering criteria |

### Related Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/buyers` | List Buyers |
| `GET` | `/v1/buyers/{buyer_id}` | Retrieve a Buyer |

Use **List Buyers** for simple retrieval and **Search Buyers** for advanced filtering using multiple conditions.

***

## 1. Search Request

Search Buyers accepts a JSON request body containing structured filtering criteria.

Each search consists of a result limit and one or more filter rules.

### Example Request

Find Buyers matching Snowbricks' Cloud-Native SaaS ICP at companies with at least 100 employees.

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/buyers/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 100,
    "filter": {
      "match": "all",
      "rules": [
        {
          "field": "icp_id",
          "operator": "eq",
          "value": "icp_363250364328685568"
        },
        {
          "field": "employee_count",
          "operator": "gte",
          "value": 100
        }
      ]
    }
  }'
```

### Request Body

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "icp_id",
        "operator": "eq",
        "value": "icp_363250364328685568"
      },
      {
        "field": "employee_count",
        "operator": "gte",
        "value": 100
      }
    ]
  }
}
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `limit` | integer | Maximum number of Buyers returned |
| `filter` | object | Container for search conditions |
| `filter.match` | string | Logical operation used to combine rules |
| `filter.rules` | array | Array of filtering conditions |
| `field` | string | Buyer attribute being filtered |
| `operator` | string | Comparison operation |
| `value` | varies | Value used for comparison |

### How Filtering Works

Each rule specifies three things:

1. **Field** – What Buyer attribute to search.
2. **Operator** – How the attribute should be compared.
3. **Value** – The value to compare against.

For example:

```json theme={null}
{
  "field": "employee_count",
  "operator": "gte",
  "value": 100
}
```

Matches Buyers associated with companies having at least 100 employees.

### Combining Multiple Rules

Use `filter.match` to control how multiple conditions are evaluated.

| Value | Logic | Description |
| - | - | - |
| `all` | AND | Every rule must match |

For example:

```json theme={null}
{
  "match": "all",
  "rules": [
    {
      "field": "icp_id",
      "operator": "eq",
      "value": "icp_363250364328685568"
    },
    {
      "field": "employee_count",
      "operator": "gte",
      "value": 100
    }
  ]
}
```

Returns Buyers who match the specified ICP **and** work at companies with at least 100 employees.

### Result Limit

`limit` controls the maximum number of Buyers returned in a response.

* Default: 100
* Maximum: 1,000
* Minimum: 1

The limit applies to the number of results returned, not the number of records evaluated.

***

## 2. Supported Buyer Filters

Search Buyers supports filtering across contact information, company attributes, ICPs, Personas, Target Lists, Signal Counts, and Attribution.

Filters operate on attributes of the existing Buyer object.

### 2.1 Contact Information

Search Buyers by their identity, role, and professional attributes.

| Field | Type | Supported Operators | Description |
| - | - | - | - |
| `name` | string | `contains` | Buyer's name |
| `email` | string | `eq`, `in`, `contains` | Work email address |
| `title` | string | `eq`, `in`, `contains` | Job title |
| `function` | string | `eq`, `in`, `contains` | Business function |
| `seniority` | string | `eq`, `in`, `contains` | Seniority level |
| `location` | string | `eq`, `in` | Contact location |
| `linkedin_followers` | number | Numeric operators | LinkedIn follower count |

### Example: VP of Data Engineering

Find Buyers with VP-level seniority whose titles contain Data Engineering.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "title",
        "operator": "contains",
        "value": "Data Engineering"
      },
      {
        "field": "seniority",
        "operator": "eq",
        "value": "vp"
      }
    ]
  }
}
```

This can help Snowbricks identify senior data engineering decision-makers.

### 2.2 Contact Availability

Find Buyers with available or verified contact information.

| Field | Type | Operators | Description |
| - | - | - | - |
| `has_email` | boolean | `eq` | Buyer has a work email |
| `has_verified_email` | boolean | `eq` | Buyer has a verified work email |
| `has_phone` | boolean | `eq` | Buyer has a mobile phone number |
| `has_verified_phone` | boolean | `eq` | Buyer has a verified mobile phone |
| `has_linkedin` | boolean | `eq` | Buyer has a LinkedIn profile |

Boolean filters accept `true` or `false`.

### Example: Buyers with Verified Contact Information

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "has_verified_email",
        "operator": "eq",
        "value": true
      },
      {
        "field": "has_linkedin",
        "operator": "eq",
        "value": true
      }
    ]
  }
}
```

Returns Buyers with verified work emails and LinkedIn profiles.

Contact availability is determined using information already available in 1eye.

**Searching does not initiate additional contact enrichment or verification.**

***

## 3. Company Filters

Search Buyers based on the characteristics of their associated companies.

| Field | Type | Supported Operators | Description |
| - | - | - | - |
| `company_name` | string | `eq`, `in`, `contains` | Company name |
| `industry` | string | `eq`, `in`, `contains` | Company industry |
| `employee_count` | number | Numeric operators | Number of employees |
| `founded_year` | number | Numeric operators | Year founded |
| `annual_revenue` | number | Numeric operators | Estimated annual revenue |
| `total_funding` | number | Numeric operators | Total funding raised |
| `company_location` | string | `eq`, `in`, `contains` | Company location |

### Numeric Operators

The following operators are supported for numeric fields:

| Operator | Description |
| - | - |
| `eq` | Equals |
| `gt` | Greater than |
| `gte` | Greater than or equal |
| `lt` | Less than |
| `lte` | Less than or equal |
| `between` | Within a specified range |

### Example: Enterprise Data Buyers

Find Buyers at software companies with at least 1,000 employees.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "industry",
        "operator": "contains",
        "value": "software"
      },
      {
        "field": "employee_count",
        "operator": "gte",
        "value": 1000
      }
    ]
  }
}
```

This can help Snowbricks identify larger organizations likely to have dedicated data infrastructure teams.

***

## 4. ICP & Persona Filters

ICPs and Personas are defined in the 1eye Knowledge Base.

ICPs describe the companies you want to target. Personas describe the people and decision-makers within those companies.

Search Buyers supports filtering using existing ICP and Persona associations.

### ICP Filters

| Field | Type | Operators | Description |
| - | - | - | - |
| `icp_id` | string | `eq`, `in` | Matched ICP identifier |

### Persona Filters

| Field | Type | Operators | Description |
| - | - | - | - |
| `persona_id` | string | `eq`, `in` | Matched Persona identifier |
| `is_persona` | boolean | `eq` | Whether Buyer matches a Persona |

### Example: ICP + Persona Matching

Find Buyers matching Snowbricks' Cloud-Native SaaS ICP and VP of Data Engineering Persona.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "icp_id",
        "operator": "eq",
        "value": "icp_363250364328685568"
      },
      {
        "field": "persona_id",
        "operator": "eq",
        "value": "per_363250364328685570"
      }
    ]
  }
}
```

This returns Buyers who satisfy both conditions.

### Searching Multiple ICPs

Use the `in` operator to match any of several ICPs.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "icp_id",
        "operator": "in",
        "value": [
          "icp_363250364328685568",
          "icp_363250364328685569"
        ]
      }
    ]
  }
}
```

### Important

ICP and Persona filters use the Buyer's existing evaluation results.

They do not trigger new ICP or Persona evaluations.

Deleted ICPs and Personas are excluded from active matching.

***

## 5. Target List Filters

Search Buyers based on their membership in Target Lists.

| Field | Type | Operators | Description |
| - | - | - | - |
| `target_list_id` | string | `eq`, `in` | Target List membership |

### Example: Buyers in a Target List

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "target_list_id",
        "operator": "eq",
        "value": "lis_123456789012345678"
      }
    ]
  }
}
```

Returns Buyers belonging to the specified Target List.

The `in` operator can be used to search across multiple Target Lists.

Target List filters use existing memberships and do not create or modify lists.

***

## 6. Signal Count Filters

Every Buyer can have associated Website, Market, and LinkedIn Signals.

The Buyer object includes summarized Signal Counts that can be used for filtering.

| Field | Type | Operators | Description |
| - | - | - | - |
| `website_signal_count` | number | Numeric operators | Number of Website Signals |
| `market_signal_count` | number | Numeric operators | Number of Market Signals |
| `linkedin_signal_count` | number | Numeric operators | Number of LinkedIn Signals |

### Example: High-Intent Buyers

Find Buyers with at least three Website Signals and one Market Signal.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "website_signal_count",
        "operator": "gte",
        "value": 3
      },
      {
        "field": "market_signal_count",
        "operator": "gte",
        "value": 1
      }
    ]
  }
}
```

This can help Snowbricks identify Buyers demonstrating engagement across multiple channels.

### How Signal Count Filtering Works

Signal Count filters operate on aggregated information already available in the Buyer object.

For example:

```json theme={null}
{
  "signal_count": {
    "total": 7,
    "website": 4,
    "market": 2,
    "linkedin": 1
  }
}
```

The Buyer above would match:

```json theme={null}
{
  "field": "website_signal_count",
  "operator": "gte",
  "value": 3
}
```

**Important:** Signal Count filters do not search individual Signal events or generate new Signals.

To search specific buying activities, use the Signals API.

***

## 7. Attribution Filters

Search Buyers based on their recorded acquisition or attribution information.

| Field | Type | Operators | Description |
| - | - | - | - |
| `attribution_type` | enum | `eq`, `in`, `not_in` | Attribution category |
| `attribution_source` | enum | `eq`, `in`, `not_in` | Attribution source |

### Attribution Types

Supported values include:

```text theme={null}
ai
direct
email
in_market
organic
paid
social
```

### Attribution Sources

Supported values include:

```text theme={null}
bing
chatgpt
claude
competitor_intent
copilot
customer_marketing
direct
duckduckgo
facebook
gemini
google
google_ads
instagram
linkedin
linkedin_ads
linkedin_comment
linkedin_follow
linkedin_reaction
meta_ads
microsoft_ads
newsletter
nurture
other
outbound
perplexity
product_intent
quora_ads
reddit
reddit_ads
tiktok_ads
topic_intent
transactional
x
x_ads
yahoo
youtube
```

### Example: Buyers from Google Ads

Find Buyers attributed to Google Ads who have verified work emails.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "attribution_source",
        "operator": "eq",
        "value": "google_ads"
      },
      {
        "field": "has_verified_email",
        "operator": "eq",
        "value": true
      }
    ]
  }
}
```

Attribution filters use information already associated with the Buyer.

Search does not recalculate attribution.

***

## 8. Timestamp Filters

Search Buyers based on when their records were created or last updated.

| Field | Type | Operators | Description |
| - | - | - | - |
| `created_at` | datetime | Datetime operators | Buyer creation timestamp |
| `updated_at` | datetime | Datetime operators | Last Buyer update timestamp |

### Datetime Operators

| Operator | Description |
| - | - |
| `gt` | After the specified time |
| `gte` | At or after the specified time |
| `lt` | Before the specified time |
| `lte` | At or before the specified time |
| `between` | Within a specified time range |
| `in_last` | Within a recent time period |

Timestamps use UTC in ISO 8601 format.

### Example: Recently Created Buyers

Find Buyers created on or after October 1, 2026.

```json theme={null}
{
  "limit": 100,
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "created_at",
        "operator": "gte",
        "value": "2026-10-01T00:00:00Z"
      }
    ]
  }
}
```

This is useful for periodically retrieving newly identified Buyers.

***

## 9. Search Operators

The available operators depend on the selected field.

| Operator | Description | Example |
| - | - | - |
| `eq` | Equals | ICP matches a specified ID |
| `in` | Matches any value in a set | ICP matches one of several IDs |
| `not_in` | Excludes specified values | Attribution source is not in a set |
| `contains` | Contains text | Company name contains "Analytics" |
| `gt` | Greater than | Employee count > 100 |
| `gte` | Greater than or equal | Employee count ≥ 100 |
| `lt` | Less than | Employee count \< 500 |
| `lte` | Less than or equal | Employee count ≤ 500 |
| `between` | Within a range | Employee count within a range |
| `in_last` | Within a recent period | Created within a recent period |

### Field-Specific Validation

Not every operator can be used with every field.

For example:

* `icp_id` supports `eq` and `in`.
* `employee_count` supports numeric operators.
* `name` supports `contains`.
* `has_verified_email` supports Boolean equality.

Unsupported field/operator combinations return validation errors.

### Value Types

Filter values must match the expected field type.

Examples:

**String**

```json theme={null}
{
  "field": "company_name",
  "operator": "contains",
  "value": "Analytics"
}
```

**Number**

```json theme={null}
{
  "field": "employee_count",
  "operator": "gte",
  "value": 100
}
```

**Boolean**

```json theme={null}
{
  "field": "has_verified_email",
  "operator": "eq",
  "value": true
}
```

**Array**

```json theme={null}
{
  "field": "icp_id",
  "operator": "in",
  "value": [
    "icp_363250364328685568",
    "icp_363250364328685569"
  ]
}
```

Invalid value types return `400 Bad Request`.

***

## 10. Response Structure

Search Buyers returns the same Buyer objects as the existing List Buyers API.

There is no separate Search Buyer response model.

### Example Response

**200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "buy_123456789012345678",
      "client_id": "wor_123456789012345678",
      "contact_info": {
        "name": {
          "first": "Jane",
          "middle": "",
          "last": "Doe"
        },
        "role": {
          "title": "VP of Data Engineering",
          "function": "engineering",
          "seniority": "vp",
          "start_date": ""
        },
        "email": {
          "work": "jane@acmeanalytics.example",
          "is_valid": true
        },
        "phone": {
          "mobile": "+14155550123",
          "is_valid": true
        },
        "social": {
          "linkedin": "https://www.linkedin.com/in/example-jane-doe",
          "twitter": "",
          "github": "",
          "facebook": "",
          "linkedin_followers": 0,
          "is_linkedin_valid": true
        },
        "location": {
          "city": "San Francisco",
          "state": "California",
          "country": "United States",
          "postal_code": ""
        },
        "photo_url": null,
        "is_persona": true,
        "persona_id": "per_363250364328685570",
        "persona_name": "VP of Data Engineering",
        "persona_reasoning": "The contact's role and responsibilities align with the VP of Data Engineering persona."
      },
      "company_info": {
        "name": "Acme Analytics",
        "website": "acmeanalytics.example",
        "logo": null,
        "industries": [
          "computer software"
        ],
        "employee_count": 250,
        "founded_year": 2018,
        "annual_revenue": 50000000,
        "company_type": "private",
        "social": {
          "linkedin": null,
          "twitter": "",
          "facebook": ""
        },
        "location": {
          "street_address": "123 Market St",
          "city": "San Francisco",
          "state": "California",
          "postal_code": "94105",
          "country": "United States"
        },
        "total_funding": 25000000,
        "latest_funding_stage": "",
        "latest_funding_round_date": "",
        "is_icp": true,
        "icp_id": "icp_363250364328685568",
        "icp_name": "Cloud-Native SaaS Companies",
        "icp_reasoning": "The company matches Snowbricks' Cloud-Native SaaS ICP."
      },
      "hems": [],
      "target_lists": [
        {
          "id": "lis_123456789012345678",
          "name": "High-Intent Data Buyers"
        }
      ],
      "signal_count": {
        "total": 7,
        "website": 4,
        "market": 2,
        "linkedin": 1
      },
      "attribution": {
        "type": "paid",
        "source": "google_ads",
        "source_name": "Google Ads",
        "source_logo": null
      },
      "first_signal_id": "sig_123456789012345678",
      "first_signal_type": "website",
      "first_signal_trigger": "visited_page",
      "last_signal_id": "sig_987654321098765432",
      "last_signal_type": "market",
      "last_signal_trigger": "researched_topic",
      "created_at": "2026-10-01T18:27:36Z",
      "updated_at": "2026-10-15T19:03:28Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

The example illustrates a Buyer relevant to Snowbricks' Cloud-Native SaaS ICP and VP of Data Engineering Persona.

Actual responses contain the Buyer records matching your search.

### Response Fields

Search Buyers preserves the existing Buyer object, including:

* Buyer identifiers.
* Contact information.
* Company information.
* ICP and Persona matches.
* Target List memberships.
* Signal Counts.
* Attribution.
* First and last Signal summaries.
* Creation and modification timestamps.

For more information about individual Buyer fields, see [Retrieve a Buyer](/api-reference/retrieve-a-buyer).

### Empty Results

If no Buyers match the search, the API returns:

**200 OK**

```json theme={null}
{
  "data": [],
  "pagination": {
    "next_cursor": null
  }
}
```

No matching Buyers is not considered an error.

***

## 11. Pagination & Sorting

Search Buyers uses cursor-based pagination, consistent with the existing 1eye Public API.

### Pagination

* Default page size: 100.
* Maximum page size: 1,000.
* Results are returned in pages.
* Each response includes `pagination.next_cursor`.
* A `null` next cursor indicates the end of the result set.

Continuation requests must preserve the original search conditions and sorting.

Cursors are opaque and must not be modified or reused with a different search.

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

### Sorting

Search results follow the existing public Buyer sorting conventions.

**Default ordering:**

```text theme={null}
created_at DESC
id DESC
```

The Buyer ID acts as a deterministic tie-breaker when multiple records share the same creation timestamp.

This ensures consistent ordering across paginated results.

See [Filtering & Sorting](/api-reference/filtering-and-sorting).

***

## 12. Buyer Search vs. Signal Search

Buyer Search and Signal Search serve different purposes.

| API | Purpose |
| - | - |
| Search Buyers | Find Buyers matching specific characteristics |
| Search Signals | Find individual buying activities |

### Buyer Search

Searches Buyer attributes and existing summaries, including:

* Contact information.
* Company characteristics.
* ICP and Persona matches.
* Target List memberships.
* Signal Counts.
* Attribution.

### Signal Search

Searches individual Website, Market, and LinkedIn Signal events.

Examples include:

* Visited a pricing page.
* Submitted a demo form.
* Researched a market topic.
* Evaluated a competitor.
* Followed a company on LinkedIn.

### Example

**Question:** Find Buyers with at least three Website Signals.

Use Search Buyers with:

```json theme={null}
{
  "field": "website_signal_count",
  "operator": "gte",
  "value": 3
}
```

**Question:** Find visitors who viewed a specific pricing page.

Use Search Signals to identify matching Website activity and its associated Buyers.

This separation ensures consistent filtering and predictable results.

***

## 13. Error Handling

Search Buyers uses the standard 1eye API error format.

| HTTP Status | Description |
| - | - |
| `200` | Search completed successfully |
| `400` | Invalid request or filter |
| `401` | Invalid or missing API key |
| `403` | Insufficient permissions |
| `429` | Workspace rate limit exceeded |
| `500` | Internal server error |

### Invalid Filter

Unsupported filter fields or operators return `400 Bad Request`.

For example, attempting to search Buyers using `url` is invalid because individual Signal URLs are not Buyer attributes.

### Example Error

**400 Bad Request**

```json theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "Unsupported Buyer search field: url.",
    "param": "filter.rules",
    "request_id": "req_359051753366339585"
  }
}
```

### Common Validation Errors

* Unknown filter field.
* Unsupported operator.
* Invalid value type.
* Invalid enum value.
* Missing or malformed filter rules.
* Invalid result limit.
* Invalid pagination cursor.

The API does not silently ignore unsupported search conditions.

For more information, see [Errors](/api-reference/errors).

***

## 14. Rate Limits & Credits

### Rate Limits

Search Buyers requests count toward your workspace API rate limits.

Rate limits are shared across all API keys belonging to the same workspace.

If a workspace exceeds its rate limit, the API returns:

**429 Too Many Requests**

Follow the `Retry-After` header when provided.

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

### Credits

**Search Buyers does not consume additional 1eye credits.**

The API searches Buyer Intelligence already available in your workspace.

It does not:

* Resolve new Buyers.
* Enrich contacts or companies.
* Verify contact information.
* Generate new Signals.
* Trigger REEM evaluations.
* Recalculate historical Buyer matches.
* Initiate Destination workflows.

Search operations are read-only.

***

## 15. Best Practices

### Combine ICP and Persona Filters

Use ICP and Persona filters together to identify Buyers who match both your ideal company profile and target decision-maker roles.

For Snowbricks, this might mean finding VP-level data engineering leaders at cloud-native SaaS companies.

### Use Signal Counts to Prioritize Engagement

Buyers showing activity across multiple channels may warrant closer review.

For example, combine Website and Market Signal Counts to find Buyers demonstrating both direct engagement and broader market research activity.

### Require Verified Contact Information

Use `has_verified_email` when building lists intended for email-based outreach.

This helps prioritize Buyers with existing verified contact data.

### Use Company Filters to Narrow Results

Combine industry, employee count, location, and funding criteria to target specific market segments.

### Use Attribution to Understand Acquisition

Filter Buyers by attribution source or type to analyze relevant audiences originating from paid, organic, social, or AI-driven discovery.

### Use Pagination for Large Result Sets

Avoid requesting unnecessarily large result sets.

Use cursor pagination to retrieve records incrementally.

### Use Signal Search for Individual Activities

When your criteria depend on specific website visits, form submissions, market research events, or LinkedIn activity, use Search Signals.

Buyer Search operates on Buyer attributes and their existing summaries.

***

## 16. Related Documentation

* [Authentication](/api-reference/auth)
* [Filtering & Sorting](/api-reference/filtering-and-sorting)
* [Pagination](/api-reference/pagination)
* [Errors](/api-reference/errors)
* [Rate Limits](/api-reference/rate-limits)
* [List Buyers](/api-reference/list-buyers)
* [Retrieve a Buyer](/api-reference/retrieve-a-buyer)
* [List Signals](/api-reference/list-signals)
* [Knowledge Base – ICPs](/knowledge-base/icps)
* [Knowledge Base – Personas](/knowledge-base/personas)


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