Create an AI field

POST/v1/campaigns/{campaign_id}/ai-fields

Scope: campaigns:write

Adds an AI field to the campaign. field_name starts with a letter and uses only letters, digits and underscores, up to 40 characters; it can't be a name the sender fills from the lead record (first_name, last_name, company, title, employee_count, industry, linkedin_from_name, email_from_name). Names are compared without regard to case, and an active field with the same name on the campaign answers 409 AI_FIELD_EXISTS.

ai_instructions say what to write for each lead. fallback_value is required: it's what a lead gets when personalization fails, so a message still reads well. data_sources is linkedin, website or both, and defaults to both.

Generating a field for each lead spends your organization's credits when the campaign sends. Preview the campaign renders every AI field at its fallback value, which costs nothing.

Headers

AuthorizationstringRequired
Bearer followed by a space and your API key, for example Bearer vk_….

Path parameters

campaign_idstring · uuidRequired
ID of the campaign.

Request body

field_namestringRequired
Used as {field_name} in messages. Letters, digits, underscores.
at most 40 characters
ai_instructionsstringRequired
What to write for each lead, and from what
at most 4,000 characters
fallback_valuestringRequired
Used when personalisation fails, so a lead still gets a sensible message
at most 300 characters
data_sourcesarray of strings or null
Where to research each lead. Defaults to both.
field_descriptionstring or null
at most 500 characters

Response

201

messagestringRequired
ai_fieldobject or null
A per-lead variable a model writes before each message, e.g. {recent_post}.
Show 9 child attributesHide child attributes
- idstringRequired
- field_namestringRequired
  The variable's name, used as {field_name} in step copy.
- ai_instructionsstringRequired
  What to write for each lead, and from what.
- created_atstring · date-time or null
- data_sourcesarray of strings or null
  Where each lead is researched: linkedin, website or both.
- fallback_valuestring or null
  What a lead gets when personalization fails, so its message still reads well.
- field_descriptionstring or null
- is_activeboolean
  Only active fields are generated. Set false to stop using a field; there's no delete.
  Default true
- updated_atstring · date-time or null
successboolean
Default true

Errors

Errors share one JSON body: success, error, message, optional details, and request_id.

Status	Code	Meaning
400	VALIDATION_ERROR	The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`.
401	UNAUTHORIZED	The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated.
401	API_KEY_EXPIRED	The API key is past its expiry date. Create a new key in the Victoria AI app.
403	INSUFFICIENT_SCOPE	The API key doesn't have the scope this endpoint requires, such as `leads:write`.
403	ORGANIZATION_DEACTIVATED	The organization that owns this API key has been deactivated.
404	CAMPAIGN_NOT_FOUND	No campaign with this ID exists in your organization.
404	NOT_FOUND	No endpoint matches the path. A resource ID in the path that isn't a valid UUID also answers `NOT_FOUND`.
409	AI_FIELD_EXISTS	An active AI field with this name already exists on the campaign. Names are compared without regard to case.
413	PAYLOAD_TOO_LARGE	The request body is larger than 1 MB.
429	RATE_LIMITED	Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See Rate limits.
500	INTERNAL_ERROR	Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support.
503	UPSTREAM_TIMEOUT	A service the API depends on timed out. The request is safe to retry.
503	AUTH_UNAVAILABLE	The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry.

Response headers

Header	Description
`X-Request-ID`	Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead.
`RateLimit-Limit`	Requests allowed to this endpoint per minute.
`RateLimit-Remaining`	Requests you can still send to this endpoint right now.
`RateLimit-Reset`	Seconds until the endpoint's full limit is available again.
`Retry-After`	On a `429`: seconds to wait before retrying.