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.
Last updated
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:
- The research result, when the sources support one.
- The field's fallback, when one is set.
- A plain line built from the lead's name, title, company, industry and size.
- 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).
| Task | Endpoint |
|---|---|
| List a campaign's fields | GET /v1/campaigns/{campaign_id}/ai-fields |
| Create a field | POST /v1/campaigns/{campaign_id}/ai-fields |
| Change a field, or stop generating it | PATCH /v1/campaigns/{campaign_id}/ai-fields/{field_id} |
| Render the sequence with every field at its fallback | POST /v1/campaigns/{campaign_id}/preview |
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.
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) fails a sequence that uses a variable no AI field or lead field provides. Set up a campaign by API 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). The REST API has no endpoint that reports how a field's values turned out; the app shows them on the campaign's leads.