# AI Personalization fields

What an AI Personalization field is, how Victoria AI fills it for each lead, what happens when the research finds nothing, and the endpoints that manage fields.

An AI Personalization field is a per-campaign variable that Victoria AI writes for each lead before its message goes out. A field is used as `{field_name}` in any step of the sequence, including an email subject line, next to the lead fields such as `{first_name}` and `{company}`.

## How a field is filled

Each field has instructions (what to write, and from what), 1 or 2 sources, and a fallback. The sources are the lead's company website and the lead's LinkedIn profile; a field can use either or both.

At send time, the field is written from 3 inputs: the lead's own columns, 1 live read of the company website, and the LinkedIn profile with up to 5 recent posts. The model writes only what those inputs support. It never invents a fact about the lead or the company.

## When the research finds nothing

When the sources don't support the field, the app works down a ladder:

1. The research result, when the sources support one.
2. The field's fallback, when one is set.
3. A plain line built from the lead's name, title, company, industry and size.
4. When none of those produces a usable value, the lead is held and retried after 24 hours.

A held lead is not skipped; it is contacted once a later attempt fills the field.

## The API surface

The REST API manages a campaign's fields. Generating them spends credits when the campaign sends, not when you call these endpoints (see [Credits](https://docs.versionseven.ai/guides/credits)).

| Task | Endpoint |
| - | - |
| List a campaign's fields | [`GET /v1/campaigns/{campaign_id}/ai-fields`](https://docs.versionseven.ai/api-reference/campaigns/list-ai-fields) |
| Create a field | [`POST /v1/campaigns/{campaign_id}/ai-fields`](https://docs.versionseven.ai/api-reference/campaigns/create-ai-field) |
| Change a field, or stop generating it | [`PATCH /v1/campaigns/{campaign_id}/ai-fields/{field_id}`](https://docs.versionseven.ai/api-reference/campaigns/update-ai-field) |
| Render the sequence with every field at its fallback | [`POST /v1/campaigns/{campaign_id}/preview`](https://docs.versionseven.ai/api-reference/campaigns/preview-campaign) |

Creating a field takes `field_name` (letters, digits and underscores, up to 40 characters), `ai_instructions` (up to 4,000 characters), `fallback_value` (up to 300 characters), an optional `field_description` (up to 500 characters) and `data_sources`, which is `["linkedin"]`, `["website"]` or both, and defaults to both. An active field with the same name on the campaign answers `409 AI_FIELD_EXISTS`.

Updating a field changes its instructions, fallback, description or sources. `field_name` can't be changed; create a new field instead. There is no delete: set `is_active: false` to stop generating the field for new leads.

> **Note:** The API requires `fallback_value` on every new field, and caps it at 300 characters. The app treats the fallback as optional, allows up to 400 characters, and holds a lead whose field has no value. When you create fields through the API, pass a fallback so the request is accepted and the lead is never held for want of one.

The preview endpoint renders variation A for up to 10 enrolled leads with every AI field at its fallback value, so you read the worst-case message before activation. It spends no credits, and it lists the fields it rendered at fallback in `ai_fields_at_fallback`.

The preflight ([`GET /v1/campaigns/{campaign_id}/preflight`](https://docs.versionseven.ai/api-reference/campaigns/get-campaign-preflight)) fails a sequence that uses a variable no AI field or lead field provides. [Set up a campaign by API](https://docs.versionseven.ai/guides/set-up-a-campaign#3-add-ai-fields) walks through creating a field alongside the rest of the campaign.

## Personalization quality

A connected assistant can read `personalization_quality` and `list_personalization_fields` over MCP (see [Connect your AI](https://docs.versionseven.ai/guides/connect-your-ai)). The REST API has no endpoint that reports how a field's values turned out; the app shows them on the campaign's leads.