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

Manage your Buyer Personas programmatically using the 1eye API. Create, retrieve, update, and delete Personas to define the people and decision-makers you want to reach within your ideal customer companies. Personas are a core component of the 1eye Knowledge Base. While ICPs define the companies you want to target, Personas define the people within those companies who are most relevant to your business. 1eye uses Personas to evaluate Buyer fit, identify relevant decision-makers, and match Buyers to your targeting criteria. Changes made through the API are automatically reflected in the 1eye Console, and vice versa.

Base URL

All Persona API requests use:

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

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/personas`	List Personas
`GET`	`/v1/kb/personas/{persona_id}`	Retrieve a Persona
`POST`	`/v1/kb/personas`	Create a Persona
`PATCH`	`/v1/kb/personas/{persona_id}`	Update a Persona
`DELETE`	`/v1/kb/personas/{persona_id}`	Delete a Persona

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

Persona Object

A Persona defines the types of people who are most likely to influence, evaluate, or purchase your products and services. Personas typically describe a buyer’s role, responsibilities, seniority, business challenges, and purchasing priorities. For example, Snowbricks, a fictional cloud data and AI platform, might target VPs of Data Engineering, Heads of Analytics, and Chief Data Officers at companies investing in modern data infrastructure.

Fields

Field	Type	Description
`name`	string	Full name of the Persona
`short_name`	string	Unique short identifier for the Persona
`description`	string	Detailed Persona definition, including roles, responsibilities, seniority, challenges, and buying priorities

Example Persona

{
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads."
}

System-Managed Fields

1eye automatically generates and maintains additional fields.

Field	Type	Description
`id`	string	Unique Persona identifier
`client_id`	string	Workspace identifier
`created_by`	object	Information about who created the Persona
`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. Persona identifiers use the per_ prefix. Example:

per_363250364328685568

1. List Personas

GET /v1/kb/personas Retrieve a paginated list of Personas configured in your workspace.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of Personas 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/personas?limit=100" \
  -H "Authorization: Bearer $API_KEY"

Example Response

200 OK

{
  "data": [
    {
      "id": "per_363250364328685568",
      "client_id": "wor_123456789012345678",
      "name": "VP of Data Engineering",
      "short_name": "vp-data-engineering",
      "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    },
    {
      "id": "per_363250364328685569",
      "client_id": "wor_123456789012345678",
      "name": "Head of Analytics",
      "short_name": "head-of-analytics",
      "description": "Analytics leaders responsible for business intelligence, reporting, data accessibility, and analytics strategy. Common titles include Head of Analytics, VP of Analytics, Director of Business Intelligence, and Head of Data Analytics. These leaders prioritize faster insights, reliable reporting, scalable analytical workloads, and reducing dependence on fragmented data tools.",
      "created_at": "2026-10-18T18:05:00Z",
      "updated_at": "2026-10-18T18:05:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}

Pagination

List Personas 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/personas?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 Personas belonging to the authenticated workspace.
Excludes soft-deleted Personas.
Supports cursor-based pagination.
Returns an empty data array when no Personas exist.
Does not return Personas belonging to other workspaces.

2. Retrieve a Persona

GET /v1/kb/personas/{persona_id} Retrieve a specific Persona using its unique identifier.

Path Parameters

Parameter	Type	Required	Description
`persona_id`	string	Yes	Unique identifier of the Persona

Example Request

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

Example Response

200 OK

{
  "id": "per_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

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

3. Create a Persona

POST /v1/kb/personas Create a new Buyer Persona in your workspace. New Personas become available for future Buyer evaluations and matching.

Request Body

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

Example Request

curl -X POST "https://api.1eye.ai/v1/kb/personas" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VP of Data Engineering",
    "short_name": "vp-data-engineering",
    "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads."
  }'

Example Response

201 Created

{
  "id": "per_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "Senior data engineering leaders at mid-market and enterprise organizations responsible for designing, scaling, and maintaining data infrastructure. Common titles include VP of Data Engineering, Head of Data Engineering, Director of Data Platform, and VP of Data Infrastructure. These leaders oversee data pipelines, cloud data warehouses, lakehouse architectures, and engineering teams supporting analytics and AI workloads. Key challenges include managing growing data volumes, reducing infrastructure costs, improving pipeline reliability, and supporting real-time analytics. They are primary technical decision-makers and influential buyers for platforms like Snowbricks that unify data warehousing, data engineering, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

When a Persona is created:

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

Important: Creating a Persona does not automatically reevaluate existing Buyers. The new Persona 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 Personas in the workspace.
System-managed fields cannot be supplied in the request.

4. Update a Persona

PATCH /v1/kb/personas/{persona_id} Update an existing Persona 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
`persona_id`	string	Yes	Unique identifier of the Persona

Request Body

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

At least one editable field must be supplied.

Example Request

Update the Persona description to include additional technical and business responsibilities.

curl -X PATCH "https://api.1eye.ai/v1/kb/personas/per_363250364328685568" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "VPs and Heads of Data Engineering at mid-market and enterprise organizations responsible for cloud data infrastructure, data platform architecture, and engineering teams. These leaders manage data pipelines, ETL/ELT workloads, lakehouse environments, data warehouses, and infrastructure supporting AI applications. They typically own or influence data platform budgets, vendor evaluations, and infrastructure modernization initiatives. Strong buying triggers include warehouse migrations, rising compute costs, real-time data requirements, platform consolidation, and initiatives to deploy generative AI and machine learning at scale."
  }'

Example Response

200 OK

{
  "id": "per_363250364328685568",
  "client_id": "wor_123456789012345678",
  "name": "VP of Data Engineering",
  "short_name": "vp-data-engineering",
  "description": "VPs and Heads of Data Engineering at mid-market and enterprise organizations responsible for cloud data infrastructure, data platform architecture, and engineering teams. These leaders manage data pipelines, ETL/ELT workloads, lakehouse environments, data warehouses, and infrastructure supporting AI applications. They typically own or influence data platform budgets, vendor evaluations, and infrastructure modernization initiatives. Strong buying triggers include warehouse migrations, rising compute costs, real-time data requirements, platform consolidation, and initiatives to deploy generative AI and machine learning at scale.",
  "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": "Head of Data Engineering"
}

Updates the Persona name without modifying its short_name or description.

Behavior

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

Important: Updating a Persona 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 a Persona

DELETE /v1/kb/personas/{persona_id} Delete a Persona from your workspace. Deleting a Persona performs a soft delete. The Persona is removed from active use but is not permanently erased from 1eye.

Path Parameters

Parameter	Type	Required	Description
`persona_id`	string	Yes	Unique identifier of the Persona

Example Request

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

Response

204 No Content The response body is empty.

What Happens When a Persona Is Deleted?

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

Impact on Existing Buyers

Deleting a Persona does not delete Buyers previously associated with that Persona. For example, Snowbricks might have identified a Buyer matching the VP of Data Engineering Persona. Before deletion:

Buyer: Jane Doe
Company: Acme Analytics
Title: VP of Data Engineering

Matched Persona:
- VP of Data Engineering

After deleting VP of Data Engineering:

Buyer: Jane Doe
Company: Acme Analytics
Title: VP of Data Engineering

Matched Persona:
- No active Persona match

The Buyer remains in 1eye, including their contact information, company information, and historical Signals. Only the deleted Persona association is removed from active matching results.

Important Considerations

Deleting a Persona does not:

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

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

6. Error Handling

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

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

Example Error

Attempting to retrieve a Persona that does not exist: 404 Not Found

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

Validation Errors

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

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

For more information, see Errors.

7. Pagination & Rate Limits

Pagination

List Personas 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

Persona 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 Personas Affect Buyer Intelligence

Personas help 1eye determine which people within your target companies are most relevant to your products and GTM strategy. The Knowledge Base is used by the REEM pipeline: Resolve → Enrich → Evaluate → Match

ICPs vs. Personas

Knowledge Base Resource	Purpose
ICPs	Define the types of companies you want to target
Personas	Define the people and decision-makers you want to reach within those companies

For example, Snowbricks might have: ICP: Cloud-Native SaaS Companies Persona: VP of Data Engineering 1eye evaluates company fit against the ICP and contact fit against the Persona. Together, these configurations help identify Buyers who are relevant to Snowbricks’ go-to-market strategy.

Impact of Persona Changes

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

Existing Buyer Evaluations

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

Deleting a Persona

Deleting a Persona removes its active Buyer associations without deleting underlying Buyer records or historical Signals.

Console Synchronization

All changes are reflected in the 1eye Console.

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

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

9. Best Practices

Use Role-Based Persona Names

Choose names that clearly identify the decision-maker or buyer segment. For Snowbricks, examples include:

VP of Data Engineering
Head of Analytics
Chief Data Officer
Director of Data Platform
Head of Machine Learning

Use Consistent Short Names

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

vp-data-engineering
head-of-analytics
chief-data-officer
director-data-platform
head-machine-learning

Write Detailed Persona Descriptions

Persona descriptions should explain who the buyer is, what they are responsible for, and why they are relevant to your product. Useful information includes:

Common job titles.
Department or business function.
Seniority level.
Primary responsibilities.
Technology ownership.
Budget and purchasing authority.
Business challenges.
Buying priorities.
Relevant evaluation or purchasing triggers.

For example, Snowbricks might target engineering leaders responsible for modernizing data infrastructure, reducing cloud data costs, and supporting AI workloads. A Persona should represent a meaningful buyer segment, not necessarily one exact job title. For example, a VP of Data Engineering Persona may include:

VP of Data Engineering
Head of Data Engineering
Director of Data Engineering
Director of Data Platform

This helps 1eye evaluate Buyers with different titles but similar responsibilities.

Focus on Responsibilities, Not Just Titles

Two Buyers may have different job titles but perform similar roles. Descriptions that include responsibilities, business challenges, and purchasing priorities provide stronger context for Persona matching than job titles alone.

Use PATCH for Updates

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

Delete Carefully

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

​Base URL

​Authentication

​Endpoints

​Persona Object

​Fields

​Example Persona

​System-Managed Fields

​1. List Personas

​Query Parameters

​Example Request

​Example Response

​Pagination

​Behavior

​2. Retrieve a Persona

​Path Parameters

​Example Request

​Example Response

​Behavior

​3. Create a Persona

​Request Body

​Example Request

​Example Response

​Behavior

​Validation

​4. Update a Persona

​Path Parameters

​Request Body

​Example Request

​Example Response

​Partial Updates

​Behavior

​5. Delete a Persona

​Path Parameters

​Example Request

​Response

​What Happens When a Persona Is Deleted?

​Impact on Existing Buyers

​Important Considerations

​6. Error Handling

​Example Error

​Validation Errors

​7. Pagination & Rate Limits

​Pagination

​Rate Limits

​8. How Personas Affect Buyer Intelligence

​ICPs vs. Personas

​Impact of Persona Changes

​Existing Buyer Evaluations

​Deleting a Persona

​Console Synchronization

​9. Best Practices

​Use Role-Based Persona Names

​Use Consistent Short Names

​Write Detailed Persona Descriptions

​Include Related Job Titles

​Focus on Responsibilities, Not Just Titles

​Use PATCH for Updates

​Delete Carefully

​10. Related Documentation

Base URL

Authentication

Endpoints

Persona Object

Fields

Example Persona

System-Managed Fields

1. List Personas

Query Parameters

Example Request

Example Response

Pagination

Behavior

2. Retrieve a Persona

Path Parameters

Example Request

Example Response

Behavior

3. Create a Persona

Request Body

Example Request

Example Response

Behavior

Validation

4. Update a Persona

Path Parameters

Request Body

Example Request

Example Response

Partial Updates

Behavior

5. Delete a Persona

Path Parameters

Example Request

Response

What Happens When a Persona Is Deleted?

Impact on Existing Buyers

Important Considerations

6. Error Handling

Example Error

Validation Errors

7. Pagination & Rate Limits

Pagination

Rate Limits

8. How Personas Affect Buyer Intelligence

ICPs vs. Personas

Impact of Persona Changes

Existing Buyer Evaluations

Deleting a Persona

Console Synchronization

9. Best Practices

Use Role-Based Persona Names

Use Consistent Short Names

Write Detailed Persona Descriptions

Include Related Job Titles

Focus on Responsibilities, Not Just Titles

Use PATCH for Updates

Delete Carefully

10. Related Documentation