> ## 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. # ICPs 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: ```text theme={null} https://api.1eye.ai/v1/kb/icps ``` ## 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/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 ```json theme={null} { "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: ```text theme={null} 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 ```bash theme={null} curl "https://api.1eye.ai/v1/kb/icps?limit=100" \ -H "Authorization: Bearer $API_KEY" ``` ### Example Response **200 OK** ```json theme={null} { "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. ```bash theme={null} 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](/api-reference/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 ```bash theme={null} curl "https://api.1eye.ai/v1/kb/icps/icp_363250364328685568" \ -H "Authorization: Bearer $API_KEY" ``` ### Example Response **200 OK** ```json theme={null} { "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 ```bash theme={null} 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** ```json theme={null} { "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: 1. 1eye generates a unique ICP ID. 2. The ICP is associated with your workspace. 3. The ICP becomes visible in the Knowledge Base. 4. The ICP becomes available for future Buyer evaluations. 5. 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. ```bash theme={null} 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** ```json theme={null} { "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: ```json theme={null} { "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 ```bash theme={null} 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:** ```text theme={null} Buyer: Jane Doe Company: Acme Analytics Matched ICPs: - Cloud-Native SaaS Companies - Data-Intensive Enterprises ``` **After deleting Cloud-Native SaaS Companies:** ```text theme={null} 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** ```json theme={null} { "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](/api-reference/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](/api-reference/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](/api-reference/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: ```text theme={null} 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. *** ## 10. 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 – ICPs](/knowledge-base/icps) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.