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

Manage Target Forms programmatically using the 1eye API. Create, retrieve, update, and delete Target Forms to identify high-intent website form submissions. Target Forms are part of the 1eye Knowledge Base. They help 1eye recognize meaningful conversion activity, such as demo requests, contact submissions, and sales inquiries. Unlike Target Pages, which identify page visits, Target Forms identify actual form submission events. Changes made through the API are reflected in the 1eye Console, and vice versa.

Base URL

All Target Form API requests use:

https://api.1eye.ai/v1/kb/target-forms

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/target-forms`	List Target Forms
`GET`	`/v1/kb/target-forms/{id}`	Retrieve a Target Form
`POST`	`/v1/kb/target-forms`	Create a Target Form
`PATCH`	`/v1/kb/target-forms/{id}`	Update a Target Form
`DELETE`	`/v1/kb/target-forms/{id}`	Delete a Target Form

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

Target Form Object

A Target Form identifies a website form associated with meaningful buying intent. For example, Snowbricks, a fictional cloud data and AI platform, might track demo requests submitted through its website.

Fields

Field	Type	Description
`name`	string	Name of the Target Form
`short_name`	string	Unique short identifier
`url`	string	URL where the form is located
`description`	string	Explanation of the form’s purpose and significance

Example Target Form

{
  "name": "Request Demo",
  "short_name": "request-demo",
  "url": "snowbricks.io/demo",
  "description": "High-intent form where prospective customers request a personalized demonstration of Snowbricks for data warehousing, lakehouse analytics, data engineering, and AI workloads."
}

System-Managed Fields

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

These fields are read-only.

1. List Target Forms

GET /v1/kb/target-forms Retrieve a paginated list of Target Forms configured in your workspace.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum records to return. Default: 100. Maximum: 1,000
`cursor`	string	No	Pagination cursor

Example Request

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

Example Response

200 OK

{
  "data": [
    {
      "id": "<target_form_id>",
      "client_id": "wor_123456789012345678",
      "name": "Request Demo",
      "short_name": "request-demo",
      "url": "snowbricks.io/demo",
      "description": "High-intent form where prospective customers request a personalized demonstration of Snowbricks for data warehousing, lakehouse analytics, data engineering, and AI workloads.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}

Pagination

When additional results exist, use pagination.next_cursor to retrieve the next page.

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

A null cursor indicates that no further results are available. See Pagination.

Behavior

Returns Target Forms belonging to the authenticated workspace.
Excludes deleted records.
Supports cursor-based pagination.
Returns an empty data array when no records exist.

2. Retrieve a Target Form

GET /v1/kb/target-forms/{id} Retrieve a specific Target Form using its unique identifier.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Target Form identifier

Example Request

curl "https://api.1eye.ai/v1/kb/target-forms/$TARGET_FORM_ID" \
  -H "Authorization: Bearer $API_KEY"

Example Response

200 OK

{
  "id": "<target_form_id>",
  "client_id": "wor_123456789012345678",
  "name": "Request Demo",
  "short_name": "request-demo",
  "url": "snowbricks.io/demo",
  "description": "High-intent form where prospective customers request a personalized demonstration of Snowbricks for data warehousing, lakehouse analytics, data engineering, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

Returns the complete Target Form record.
Includes applicable system metadata.
Returns 404 Not Found if the form does not exist, has been deleted, or belongs to another workspace.

3. Create a Target Form

POST /v1/kb/target-forms Create a new Target Form in your workspace.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Target Form name
`short_name`	string	Yes	Unique short identifier
`url`	string	Yes	URL containing the form
`description`	string	Yes	Description of the form’s significance

Example Request

curl -X POST "https://api.1eye.ai/v1/kb/target-forms" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Request Demo",
    "short_name": "request-demo",
    "url": "snowbricks.io/demo",
    "description": "High-intent form where prospective customers request a personalized demonstration of Snowbricks for data warehousing, lakehouse analytics, data engineering, and AI workloads."
  }'

Example Response

201 Created

{
  "id": "<target_form_id>",
  "client_id": "wor_123456789012345678",
  "name": "Request Demo",
  "short_name": "request-demo",
  "url": "snowbricks.io/demo",
  "description": "High-intent form where prospective customers request a personalized demonstration of Snowbricks for data warehousing, lakehouse analytics, data engineering, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

When a Target Form is created:

1eye generates a unique identifier.
The Target Form is associated with the workspace.
It appears in the Knowledge Base.
It becomes available for future Website Signals processing.
It can be retrieved or updated through the API.

Important: Creating a Target Form does not automatically detect past submissions or generate historical Signals.

Validation

All four fields must contain valid values.
short_name must be unique among active Target Forms in the workspace.
url must identify a valid website location.
System-managed fields cannot be supplied.

4. Update a Target Form

PATCH /v1/kb/target-forms/{id} Update an existing Target Form. Only fields included in the request are modified.

Request Body

Field	Type	Required
`name`	string	No
`short_name`	string	No
`url`	string	No
`description`	string	No

At least one editable field must be supplied.

Example Request

curl -X PATCH "https://api.1eye.ai/v1/kb/target-forms/$TARGET_FORM_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "High-intent conversion form submitted by prospective Snowbricks customers requesting a technical demonstration, proof of concept, or enterprise evaluation of the Snowbricks data platform."
  }'

Example Response

200 OK

{
  "id": "<target_form_id>",
  "client_id": "wor_123456789012345678",
  "name": "Request Demo",
  "short_name": "request-demo",
  "url": "snowbricks.io/demo",
  "description": "High-intent conversion form submitted by prospective Snowbricks customers requesting a technical demonstration, proof of concept, or enterprise evaluation of the Snowbricks data platform.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}

Behavior

Supports partial updates.
Preserves omitted fields.
Maintains the original resource identifier.
Reflects changes in the Console.
Uses the updated configuration for future processing.
Does not retroactively reprocess historical form submissions.

5. Delete a Target Form

DELETE /v1/kb/target-forms/{id} Delete a Target Form from your workspace. Deletion performs a soft delete.

Example Request

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

Response

204 No Content The response body is empty.

What Happens When a Target Form Is Deleted?

The Target Form is removed from the active Knowledge Base.
It is excluded from future Target Form matching.
It no longer appears in List Target Forms.
Retrieving the deleted record returns 404 Not Found.
Historical form-submission Signals remain preserved.

Deleting a Target Form does not delete Buyers, historical conversions, or existing Signals. Restoring deleted Target Forms is not currently exposed through the public API.

6. Form Detection & URL Matching

Form Detection

Target Forms identify actual form-submission activity. For example, a visitor to:

snowbricks.io/demo

may:

Visit the demo page.
Fill in a form.
Submit the form.

A Target Form represents the qualifying submission event, not simply the page visit. Important: Adding a Target Form does not automatically guarantee that submissions will be detected. The 1eye Website pixel must be installed and capable of detecting the form interaction.

URL Matching

Target Forms use exact matching against a normalized canonical URL. 1eye handles URL normalization automatically. For example:

https://snowbricks.io/demo
https://snowbricks.io/demo/
https://snowbricks.io/demo?utm_source=linkedin
snowbricks.io/demo

These should resolve to the same canonical page. There is no configurable match_type field. A separate domain field is not required because the domain is derived from the URL.

Target Page vs. Target Form

Resource	Activity
Target Page	Visitor viewed a configured page
Target Form	Visitor submitted a configured form

A visitor may generate a Target Page event without generating a Target Form event.

7. Error Handling

All Target Form endpoints use the standard 1eye API error format.

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

Example Error

404 Not Found

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

See Errors.

8. Pagination & Rate Limits

List Target Forms supports cursor-based pagination.

Default page size: 100.
Maximum page size: 1,000.
cursor retrieves subsequent pages.
next_cursor: null indicates the end of the collection.

Target Form API requests count toward your workspace API rate limits. See Pagination and Rate Limits.

9. How Target Forms Affect Website Signals

Target Forms help 1eye recognize high-intent website conversion activity. For Snowbricks, examples include:

Target Form	Buying Intent
Request Demo	Sales evaluation
Contact Sales	Direct sales inquiry
Request Enterprise Trial	Product evaluation
Request Technical Consultation	Technical assessment

Knowledge Base Integration

Operation	Impact
Create	Form becomes available for future matching
Update	Updated configuration applies to future matching
Delete	Form is removed from active Target Form matching

Console Synchronization

All changes made through the API are reflected in the 1eye Console, and vice versa.

10. Best Practices

Track High-Intent Forms

Prioritize forms indicating meaningful customer interest. Examples:

Demo requests.
Contact Sales.
Enterprise trial requests.
Technical evaluations.

Use Clear Names

Request Demo
Contact Sales
Enterprise Trial
Technical Consultation

Use Consistent Short Names

request-demo
contact-sales
enterprise-trial
technical-consultation

Provide Accurate Form URLs

Use the webpage where the form is embedded or submitted. Avoid unnecessary tracking parameters.

Describe the Conversion

Use the description to explain why the form matters to your go-to-market strategy.

Verify Form Detection

Ensure the 1eye Website pixel is installed and submissions are being detected correctly.

​Base URL

​Authentication

​Endpoints

​Target Form Object

​Fields

​Example Target Form

​System-Managed Fields

​1. List Target Forms

​Query Parameters

​Example Request

​Example Response

​Pagination

​Behavior

​2. Retrieve a Target Form

​Path Parameters

​Example Request

​Example Response

​Behavior

​3. Create a Target Form

​Request Body

​Example Request

​Example Response

​Behavior

​Validation

​4. Update a Target Form

​Request Body

​Example Request

​Example Response

​Behavior

​5. Delete a Target Form

​Example Request

​Response

​What Happens When a Target Form Is Deleted?

​6. Form Detection & URL Matching

​Form Detection

​URL Matching

​Target Page vs. Target Form

​7. Error Handling

​Example Error

​8. Pagination & Rate Limits

​9. How Target Forms Affect Website Signals

​Knowledge Base Integration

​Console Synchronization

​10. Best Practices

​Track High-Intent Forms

​Use Clear Names

​Use Consistent Short Names

​Provide Accurate Form URLs

​Describe the Conversion

​Verify Form Detection

​11. Related Documentation

Base URL

Authentication

Endpoints

Target Form Object

Fields

Example Target Form

System-Managed Fields

1. List Target Forms

Query Parameters

Example Request

Example Response

Pagination

Behavior

2. Retrieve a Target Form

Path Parameters

Example Request

Example Response

Behavior

3. Create a Target Form

Request Body

Example Request

Example Response

Behavior

Validation

4. Update a Target Form

Request Body

Example Request

Example Response

Behavior

5. Delete a Target Form

Example Request

Response

What Happens When a Target Form Is Deleted?

6. Form Detection & URL Matching

Form Detection

URL Matching

Target Page vs. Target Form

7. Error Handling

Example Error

8. Pagination & Rate Limits

9. How Target Forms Affect Website Signals

Knowledge Base Integration

Console Synchronization

10. Best Practices

Track High-Intent Forms

Use Clear Names

Use Consistent Short Names

Provide Accurate Form URLs

Describe the Conversion

Verify Form Detection

11. Related Documentation