> ## 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.

# Target Forms

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:

```text theme={null}
https://api.1eye.ai/v1/kb/target-forms
```

## 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/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

```json theme={null}
{
  "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

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

### Example Response

**200 OK**

```json theme={null}
{
  "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.

```bash theme={null}
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](/api-reference/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

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/target-forms/$TARGET_FORM_ID" \
  -H "Authorization: Bearer $API_KEY"
```

### Example Response

**200 OK**

```json theme={null}
{
  "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

```bash theme={null}
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**

```json theme={null}
{
  "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:

1. 1eye generates a unique identifier.
2. The Target Form is associated with the workspace.
3. It appears in the Knowledge Base.
4. It becomes available for future Website Signals processing.
5. 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

```bash theme={null}
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**

```json theme={null}
{
  "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

```bash theme={null}
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:

```text theme={null}
snowbricks.io/demo
```

may:

1. Visit the demo page.
2. Fill in a form.
3. 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:

```text theme={null}
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**

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Target Form not found.",
    "request_id": "req_359051753366339585"
  }
}
```

See [Errors](/api-reference/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](/api-reference/pagination) and [Rate Limits](/api-reference/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

```text theme={null}
Request Demo
Contact Sales
Enterprise Trial
Technical Consultation
```

### Use Consistent Short Names

```text theme={null}
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.

***

## 11. Related Documentation

* [Authentication](/api-reference/auth)
* [Pagination](/api-reference/pagination)
* [Errors](/api-reference/errors)
* [Rate Limits](/api-reference/rate-limits)
* [List Signals](/api-reference/list-signals)
* [Knowledge Base – Target Forms](/knowledge-base/target-forms)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.