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

Manage your Ideal Customer Profiles (ICPs) programmatically using the 1eye API. Create, retrieve, update, and delete ICPs to define the types of companies that represent your ideal customers. ICPs are a core component of the 1eye Knowledge Base. They help 1eye evaluate company fit, qualify potential customers, and match Buyers to your ideal customer profiles. Changes made through the API are automatically reflected in the 1eye Console, and vice versa.

Base URL

All ICP API requests use:

https://api.1eye.ai/v1/kb/icps

Authentication

All endpoints require a valid 1eye API key.

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.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/kb/icps`	List ICPs
`GET`	`/v1/kb/icps/{icp_id}`	Retrieve an ICP
`POST`	`/v1/kb/icps`	Create an ICP
`PATCH`	`/v1/kb/icps/{icp_id}`	Update an ICP
`DELETE`	`/v1/kb/icps/{icp_id}`	Delete an ICP

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

ICP Object

An Ideal Customer Profile defines the characteristics of companies that are a strong fit for your business. For example, Snowbricks, a fictional cloud data platform, might target cloud-native SaaS companies and data-intensive enterprises that need scalable analytics, data engineering, and AI infrastructure.

Fields

Field	Type	Description
`name`	string	Full name of the ICP
`short_name`	string	Unique short identifier for the ICP
`description`	string	Detailed definition of the ICP, including company characteristics, business needs, and targeting criteria

Example ICP

{
  "name": "Cloud-Native SaaS Companies",
  "short_name": "cloud-native-saas",
  "description": "B2B SaaS companies in North America with 100–2,000 employees that manage growing volumes of product, customer, and operational data. These companies typically have dedicated data engineering teams, multiple data sources, and increasing demand for real-time analytics and AI workloads. They are strong candidates for Snowbricks because they need to unify data warehousing, lakehouse analytics, and machine learning without maintaining separate platforms. Common buying triggers include migrating legacy data warehouses, consolidating analytics infrastructure, reducing query costs, and launching AI-powered products."
}

System-Managed Fields

1eye automatically generates and maintains additional fields.

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

These fields are read-only and cannot be modified through Create or Update requests. ICP identifiers use the icp_ prefix. Example:

icp_363250364328685568

1. List ICPs

GET /v1/kb/icps Retrieve a paginated list of ICPs configured in your workspace.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of ICPs to return. Default: 100. Maximum: 1,000
`cursor`	string	No	Pagination cursor returned by a previous request

Example Request

curl "https://api.1eye.ai/v1/kb/icps?limit=100" \
  -H "Authorization: Bearer $API_KEY"

Example Response

200 OK

{
  "data": [
    {
      "id": "icp_363250364328685568",
      "client_id": "wor_123456789012345678",
      "name": "Cloud-Native SaaS Companies",
      "short_name": "cloud-native-saas",
      "description": "B2B SaaS companies in North America with 100–2,000 employees that manage growing volumes of product, customer, and operational data. These companies typically have dedicated data engineering teams and need scalable analytics, data warehousing, and AI infrastructure.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    },
    {
      "id": "icp_363250364328685569",
      "client_id": "wor_123456789012345678",
      "name": "Data-Intensive Enterprises",
      "short_name": "data-intensive-enterprises",
      "description": "Large enterprises with 1,000+ employees operating complex data platforms across cloud and on-premise environments. These organizations typically have multiple business units, large analytics workloads, and dedicated data engineering and AI teams. They need unified data infrastructure, scalable processing, governance, and cost optimization.",
      "created_at": "2026-10-18T18:05:00Z",
      "updated_at": "2026-10-18T18:05:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}

Pagination

List ICPs uses cursor-based pagination. When additional results are available, pagination.next_cursor contains a continuation token. Pass this token using the cursor parameter to retrieve the next page.

curl "https://api.1eye.ai/v1/kb/icps?limit=100&cursor=YOUR_CURSOR" \
  -H "Authorization: Bearer $API_KEY"

When next_cursor is null, there are no additional results. For more information, see Pagination.

Behavior

Returns ICPs belonging to the authenticated workspace.
Excludes soft-deleted ICPs.
Supports cursor-based pagination.
Returns an empty data array when no ICPs exist.
Does not return ICPs belonging to other workspaces.

2. Retrieve an ICP

GET /v1/kb/icps/{icp_id} Retrieve a specific ICP using its unique identifier.

Path Parameters

Parameter	Type	Required	Description
`icp_id`	string	Yes	Unique identifier of the ICP

Example Request

curl "https://api.1eye.ai/v1/kb/icps/icp_363250364328685568" \
  -H "Authorization: Bearer $API_KEY"

Example Response

200 OK

{
  "id": "icp_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "Cloud-Native SaaS Companies",
  "short_name": "cloud-native-saas",
  "description": "B2B SaaS companies in North America with 100–2,000 employees that manage growing volumes of product, customer, and operational data. These companies typically have dedicated data engineering teams, multiple data sources, and increasing demand for real-time analytics and AI workloads. They are strong candidates for Snowbricks because they need to unify data warehousing, lakehouse analytics, and machine learning without maintaining separate platforms. Common buying triggers include migrating legacy data warehouses, consolidating analytics infrastructure, reducing query costs, and launching AI-powered products.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

Returns the complete ICP record.
Includes system-generated metadata.
The ICP must belong to the authenticated workspace.
Returns 404 Not Found if the ICP does not exist, has been deleted, or belongs to another workspace.

3. Create an ICP

POST /v1/kb/icps Create a new Ideal Customer Profile in your workspace. New ICPs become available for future Buyer evaluations and matching.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Full ICP name
`short_name`	string	Yes	Unique short identifier
`description`	string	Yes	Detailed ICP definition

Example Request

curl -X POST "https://api.1eye.ai/v1/kb/icps" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloud-Native SaaS Companies",
    "short_name": "cloud-native-saas",
    "description": "B2B SaaS companies in North America with 100–2,000 employees that manage growing volumes of product, customer, and operational data. These companies typically have dedicated data engineering teams, multiple data sources, and increasing demand for real-time analytics and AI workloads. They are strong candidates for Snowbricks because they need to unify data warehousing, lakehouse analytics, and machine learning without maintaining separate platforms. Common buying triggers include migrating legacy data warehouses, consolidating analytics infrastructure, reducing query costs, and launching AI-powered products."
  }'

Example Response

201 Created

{
  "id": "icp_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "Cloud-Native SaaS Companies",
  "short_name": "cloud-native-saas",
  "description": "B2B SaaS companies in North America with 100–2,000 employees that manage growing volumes of product, customer, and operational data. These companies typically have dedicated data engineering teams, multiple data sources, and increasing demand for real-time analytics and AI workloads. They are strong candidates for Snowbricks because they need to unify data warehousing, lakehouse analytics, and machine learning without maintaining separate platforms. Common buying triggers include migrating legacy data warehouses, consolidating analytics infrastructure, reducing query costs, and launching AI-powered products.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

When an ICP is created:

1eye generates a unique ICP ID.
The ICP is associated with your workspace.
The ICP becomes visible in the Knowledge Base.
The ICP becomes available for future Buyer evaluations.
The ICP can immediately be retrieved or updated through the API.

Important: Creating an ICP does not automatically reevaluate existing Buyers. The new ICP is used during subsequent Buyer evaluations.

Validation

name must not be empty.
short_name must not be empty.
description must not be empty.
short_name must be unique among active ICPs in the workspace.
System-managed fields cannot be supplied in the request.

4. Update an ICP

PATCH /v1/kb/icps/{icp_id} Update an existing ICP using its unique identifier. The API supports partial updates. You only need to provide the fields you want to change.

Path Parameters

Parameter	Type	Required	Description
`icp_id`	string	Yes	Unique identifier of the ICP

Request Body

Field	Type	Required	Description
`name`	string	No	Updated ICP name
`short_name`	string	No	Updated short identifier
`description`	string	No	Updated ICP definition

At least one editable field must be supplied.

Example Request

Update the description to further qualify Snowbricks’ ideal customers.

curl -X PATCH "https://api.1eye.ai/v1/kb/icps/icp_363250364328685568" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Cloud-native B2B SaaS companies in North America with 100–2,000 employees, dedicated data engineering teams, and rapidly growing analytics or AI workloads. Ideal companies operate on AWS, Azure, or Google Cloud and are actively evaluating ways to consolidate data warehousing, lakehouse analytics, and machine learning infrastructure. Strong buying signals include warehouse migrations, rising query costs, real-time analytics requirements, and investment in generative AI applications."
  }'

Example Response

200 OK

{
  "id": "icp_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "Cloud-Native SaaS Companies",
  "short_name": "cloud-native-saas",
  "description": "Cloud-native B2B SaaS companies in North America with 100–2,000 employees, dedicated data engineering teams, and rapidly growing analytics or AI workloads. Ideal companies operate on AWS, Azure, or Google Cloud and are actively evaluating ways to consolidate data warehousing, lakehouse analytics, and machine learning infrastructure. Strong buying signals include warehouse migrations, rising query costs, real-time analytics requirements, and investment in generative AI applications.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}

Partial Updates

Only the fields supplied in the request are updated. For example:

{
  "name": "High-Growth SaaS Companies"
}

Updates the ICP name without modifying its short_name or description.

Behavior

Updates the existing ICP.
Preserves fields not included in the request.
Preserves the original ICP ID.
Updates the modification timestamp.
Reflects changes in the 1eye Console.
Uses the updated ICP definition for future Buyer evaluations.

Important: Updating an ICP does not automatically trigger historical Buyer reevaluation. Existing Buyer evaluation results remain unchanged until they are reevaluated through the normal 1eye processing pipeline.

5. Delete an ICP

DELETE /v1/kb/icps/{icp_id} Delete an ICP from your workspace. Deleting an ICP performs a soft delete. The ICP is removed from active use but is not permanently erased from 1eye.

Path Parameters

Parameter	Type	Required	Description
`icp_id`	string	Yes	Unique identifier of the ICP

Example Request

curl -X DELETE "https://api.1eye.ai/v1/kb/icps/icp_363250364328685568" \
  -H "Authorization: Bearer $API_KEY"

Response

204 No Content The response body is empty.

What Happens When an ICP Is Deleted?

The ICP is removed from the active Knowledge Base.
The ICP no longer appears in List ICPs results.
Retrieving the deleted ICP returns 404 Not Found.
The ICP is excluded from future Buyer evaluations.
The deleted ICP is removed from active Buyer ICP associations.
Historical ICP information is preserved internally.

Impact on Existing Buyers

Deleting an ICP does not delete Buyers previously associated with that ICP. For example, a Buyer at a software company might match multiple ICPs. Before deletion:

Buyer: Jane Doe
Company: Acme Analytics

Matched ICPs:
- Cloud-Native SaaS Companies
- Data-Intensive Enterprises

After deleting Cloud-Native SaaS Companies:

Buyer: Jane Doe
Company: Acme Analytics

Matched ICPs:
- Data-Intensive Enterprises

The Buyer remains in 1eye. Only the deleted ICP association is removed from active matching results.

Important Considerations

Deleting an ICP does not:

Delete Buyers.
Delete Signals.
Permanently erase historical evaluations.
Delete previously synchronized CRM contacts.
Automatically trigger new Buyer evaluations.

Restoring deleted ICPs is not currently exposed through the public API.

6. Error Handling

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

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

Example Error

Attempting to retrieve an ICP that does not exist: 404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "ICP not found.",
    "request_id": "req_359051753366339585"
  }
}

Validation Errors

Invalid requests return an error identifying the issue. Examples include:

Missing ICP name.
Missing short name.
Empty description.
Duplicate short name.
Invalid ICP ID.
Attempting to modify system-managed fields.

For more information, see Errors.

7. Pagination & Rate Limits

Pagination

List ICPs supports the existing 1eye cursor-based pagination mechanism.

Default page size: 100.
Maximum page size: 1,000.
Use cursor to retrieve subsequent pages.
A null next cursor indicates the end of the collection.

See Pagination.

Rate Limits

ICP API requests count toward your workspace’s API rate limits. Rate limits are shared across all API keys belonging to the same workspace. If a limit is exceeded, the API returns: 429 Too Many Requests Follow the Retry-After header when provided. See Rate Limits.

8. How ICP Changes Affect Buyer Intelligence

ICPs help 1eye determine which companies match your ideal customer profiles. The Knowledge Base is used by the REEM pipeline: Resolve → Enrich → Evaluate → Match

Operation	Impact
Create	New ICP becomes available for future Buyer evaluations
Update	Updated ICP definition is used for future evaluations
Delete	ICP is removed from active matching and future evaluations

Existing Buyer Evaluations

Creating or updating an ICP does not automatically reevaluate existing Buyers. Existing evaluations are preserved until the normal REEM pipeline processes them again.

Deleting an ICP

Deleting an ICP removes it from active Buyer matching without deleting underlying Buyer records or historical Signals.

Console Synchronization

All changes are reflected in the 1eye Console.

ICPs created through the API appear in the Console.
Console updates are reflected in API responses.
Deleted ICPs no longer appear in active Knowledge Base views.

The API and Console operate on the same underlying Knowledge Base.

9. Best Practices

Use Descriptive ICP Names

Choose names that clearly identify the customer segment. For Snowbricks, examples include:

Cloud-Native SaaS Companies
Data-Intensive Enterprises
AI-Native Startups
Financial Services Data Platforms

Use Consistent Short Names

Short names should be concise, descriptive, and unique within your workspace. Examples:

cloud-native-saas
data-intensive-enterprises
ai-native-startups
financial-services-data

Write Detailed Descriptions

ICP descriptions should explain what makes a company a strong potential customer. Useful information includes:

Industry and business model.
Company size and geographic focus.
Existing technology infrastructure.
Business challenges and technical requirements.
Relevant buying triggers.
Characteristics that indicate strong product fit.

For example, Snowbricks might prioritize companies migrating from legacy data warehouses, adopting lakehouse architectures, or building AI-powered products. The more clearly an ICP describes your ideal customers, the more useful it becomes during Buyer evaluation and matching.

Use PATCH for Updates

Update only the fields that need to change. Avoid replacing complete ICP definitions when a partial update is sufficient.

Delete Carefully

Deleting an ICP removes it from active Buyer matching. Before deleting an ICP, consider how it is currently used across Buyer Intelligence and your GTM workflows.

​Base URL

​Authentication

​Endpoints

​ICP Object

​Fields

​Example ICP

​System-Managed Fields

​1. List ICPs

​Query Parameters

​Example Request

​Example Response

​Pagination

​Behavior

​2. Retrieve an ICP

​Path Parameters

​Example Request

​Example Response

​Behavior

​3. Create an ICP

​Request Body

​Example Request

​Example Response

​Behavior

​Validation

​4. Update an ICP

​Path Parameters

​Request Body

​Example Request

​Example Response

​Partial Updates

​Behavior

​5. Delete an ICP

​Path Parameters

​Example Request

​Response

​What Happens When an ICP Is Deleted?

​Impact on Existing Buyers

​Important Considerations

​6. Error Handling

​Example Error

​Validation Errors

​7. Pagination & Rate Limits

​Pagination

​Rate Limits

​8. How ICP Changes Affect Buyer Intelligence

​Existing Buyer Evaluations

​Deleting an ICP

​Console Synchronization

​9. Best Practices

​Use Descriptive ICP Names

​Use Consistent Short Names

​Write Detailed Descriptions

​Use PATCH for Updates

​Delete Carefully

​10. Related Documentation

Base URL

Authentication

Endpoints

ICP Object

Fields

Example ICP

System-Managed Fields

1. List ICPs

Query Parameters

Example Request

Example Response

Pagination

Behavior

2. Retrieve an ICP

Path Parameters

Example Request

Example Response

Behavior

3. Create an ICP

Request Body

Example Request

Example Response

Behavior

Validation

4. Update an ICP

Path Parameters

Request Body

Example Request

Example Response

Partial Updates

Behavior

5. Delete an ICP

Path Parameters

Example Request

Response

What Happens When an ICP Is Deleted?

Impact on Existing Buyers

Important Considerations

6. Error Handling

Example Error

Validation Errors

7. Pagination & Rate Limits

Pagination

Rate Limits

8. How ICP Changes Affect Buyer Intelligence

Existing Buyer Evaluations

Deleting an ICP

Console Synchronization

9. Best Practices

Use Descriptive ICP Names

Use Consistent Short Names

Write Detailed Descriptions

Use PATCH for Updates

Delete Carefully

10. Related Documentation