1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

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:

https://api.1eye.ai/v1/buyers/search

Authentication

All requests require a valid 1eye API key.

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.

Endpoint

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

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.

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

{
  "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:

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

For example:

{
  "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:

{
  "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.

{
  "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

{
  "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.

{
  "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.

{
  "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.

{
  "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

{
  "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.

{
  "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:

{
  "signal_count": {
    "total": 7,
    "website": 4,
    "market": 2,
    "linkedin": 1
  }
}

The Buyer above would match:

{
  "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:

ai
direct
email
in_market
organic
paid
social

Attribution Sources

Supported values include:

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.

{
  "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.

{
  "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

{
  "field": "company_name",
  "operator": "contains",
  "value": "Analytics"
}

Number

{
  "field": "employee_count",
  "operator": "gte",
  "value": 100
}

Boolean

{
  "field": "has_verified_email",
  "operator": "eq",
  "value": true
}

Array

{
  "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

{
  "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.

Empty Results

If no Buyers match the search, the API returns: 200 OK

{
  "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.

Sorting

Search results follow the existing public Buyer sorting conventions. Default ordering:

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.

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:

{
  "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

{
  "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.

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.

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.

​Base URL

​Authentication

​Endpoint

​Related Endpoints

​1. Search Request

​Example Request

​Request Body

​Parameters

​How Filtering Works

​Combining Multiple Rules

​Result Limit

​2. Supported Buyer Filters

​2.1 Contact Information

​Example: VP of Data Engineering

​2.2 Contact Availability

​Example: Buyers with Verified Contact Information

​3. Company Filters

​Numeric Operators

​Example: Enterprise Data Buyers

​4. ICP & Persona Filters

​ICP Filters

​Persona Filters

​Example: ICP + Persona Matching

​Searching Multiple ICPs

​Important

​5. Target List Filters

​Example: Buyers in a Target List

​6. Signal Count Filters

​Example: High-Intent Buyers

​How Signal Count Filtering Works

​7. Attribution Filters

​Attribution Types

​Attribution Sources

​Example: Buyers from Google Ads

​8. Timestamp Filters

​Datetime Operators

​Example: Recently Created Buyers

​9. Search Operators

​Field-Specific Validation

​Value Types

​10. Response Structure

​Example Response

​Response Fields

​Empty Results

​11. Pagination & Sorting

​Pagination

​Sorting

​12. Buyer Search vs. Signal Search

​Buyer Search

​Signal Search

​Example

​13. Error Handling

​Invalid Filter

​Example Error

​Common Validation Errors

​14. Rate Limits & Credits

​Rate Limits

​Credits

​15. Best Practices

​Combine ICP and Persona Filters

​Use Signal Counts to Prioritize Engagement

​Require Verified Contact Information

​Use Company Filters to Narrow Results

​Use Attribution to Understand Acquisition

​Use Pagination for Large Result Sets

​Use Signal Search for Individual Activities

​16. Related Documentation