AI Variables - Enginy API Docs

Overview

AI Variables let you define reusable AI-powered fields for contacts and companies. The new OpenAPI section covers the full lifecycle:

List AI Variables: GET /v1/ai-variables
Get one AI Variable: GET /v1/ai-variables/{aiVariableId}
Create an AI Variable: POST /v1/ai-variables
Update an AI Variable: PATCH /v1/ai-variables/{aiVariableId}
Delete an AI Variable: DELETE /v1/ai-variables/{aiVariableId}
List contact AI Variable folders: GET /v1/ai-variables/folders/contacts
List company AI Variable folders: GET /v1/ai-variables/folders/companies
List AI message folders: GET /v1/ai-variables/folders/ai-messages
List AI snippet folders: GET /v1/ai-variables/folders/ai-snippets
List message template folders: GET /v1/ai-variables/folders/message-templates
Create, update, get, and delete folder endpoints under those same folder paths

It also adds field-discovery endpoints so you can see exactly which placeholders are valid:

Contact fields: GET /v1/contacts/fields
Company fields: GET /v1/companies/fields

Workspaces on the split AI-entity model additionally manage AI messages, AI snippets, and message templates through their own endpoints — see AI Messages, AI Snippets, and Message Templates.

Mental Model

An AI Variable is defined by the prompt you write, the entity it belongs to, and the output format you expect back. The /v1/ai-variables CRUD endpoints manage AI research: a research/enrichment value computed per contact or company (classifications, extracted facts, findings). Outreach content is a different entity type — personalized outbound messages are AI messages, reusable AI-generated fragments are AI snippets, and literal (non-AI-generated) sequences are message templates. Send prompt as plain text and Enginy handles the internal prompt representation automatically.

Prompt Format

Reference fields with curly braces:

Write a short intro for {firstName} at {companyName} using {jobTitle} and {lastLinkedInPost}.

Use the exact id returned by the field-discovery endpoints. If you send an unknown placeholder, the API returns a validation error starting with Invalid placeholders detected.

Request Format

Minimal create payload

{
  "name": "iceBreaker",
  "entity": "CONTACT",
  "prompt": "Write a short intro for {firstName} at {companyName}."
}

Structured create payload

{
  "name": "accountPriority",
  "entity": "COMPANY",
  "prompt": "Classify {name} as High, Medium, or Low priority based on {industry} and {numberOfEmployees}.",
  "outputSchema": {
    "type": "oneOf",
    "values": ["High", "Medium", "Low"]
  },
  "search": true
}

AI Variable Fields

Field	Type	Required	Notes
`name`	string	yes on create	Must be unique per entity
`entity`	`CONTACT` \| `COMPANY`	yes on create	Determines where the generated value is stored
`prompt`	string	yes on create	Plain-text prompt template
`model`	string \| null	no	Optional model ID
`outputSchema`	object	no	Defaults to `{ "type": "text", "provideExplanation": false }`
`search`	boolean	no	Deep Search toggle. `true` enables Deep Search, `false` disables it
`folderId`	number \| null	no	Folder used for organization. Folder ids are per entity type (contact, company, AI message, AI snippet, message template) — a folder id from one entity type is rejected with 400 on another. Use the AI Variable folder endpoints to discover or manage folder IDs
`customWebsiteField`	string \| null	no	Optional custom website field source

`outputSchema` Format

outputSchema describes the expected AI output.

Field	Type	Notes
`type`	`text` \| `number` \| `date` \| `oneOf` \| `anyOf` \| `url` \| `email`	Required. `oneOf` returns a single option; `anyOf` returns every matching option as a comma-separated list
`values`	string[]	Required when `type` is `oneOf` or `anyOf`. Requests fail validation if this array is missing or empty
`provideExplanation`	boolean	Optional
`jsonSchema`	JSON value	Optional advanced override

`search` Toggle

search is a boolean:

true: enable Deep Search
false: disable Deep Search

Folder Endpoints

Folder trees are kept per entity type. A folder id from one tree is not valid for another: passing a contact or company AI Variable folder id as folderId on an AI message, AI snippet, or message template returns 400 (Folder not found or entity mismatch). Discover or create folders through the endpoints of the entity you are writing. AI research variables (contact and company entities):

Contact folders: GET|POST /v1/ai-variables/folders/contacts
Contact folder detail/update/delete: GET|PATCH|DELETE /v1/ai-variables/folders/contacts/{folderId}
Company folders: GET|POST /v1/ai-variables/folders/companies
Company folder detail/update/delete: GET|PATCH|DELETE /v1/ai-variables/folders/companies/{folderId}

Split AI entities (require the AI variable split to be enabled for the workspace; otherwise 403):

AI message folders: GET|POST /v1/ai-variables/folders/ai-messages and GET|PATCH|DELETE /v1/ai-variables/folders/ai-messages/{folderId}
AI snippet folders: GET|POST /v1/ai-variables/folders/ai-snippets and GET|PATCH|DELETE /v1/ai-variables/folders/ai-snippets/{folderId}
Message template folders: GET|POST /v1/ai-variables/folders/message-templates and GET|PATCH|DELETE /v1/ai-variables/folders/message-templates/{folderId}

Folder detail responses list the items directly inside the folder under aiVariables (AI research fields for contact/company folders; a slim { id, name, description, folderId, createdAt, updatedAt } shape for AI message, AI snippet, and message template folders). Deleting a folder does not delete the items inside it. Enginy moves those items, and any child folders, up to the deleted folder’s parent.

Discovering Valid Field Names

Before writing prompts, fetch the available fields for the relevant entity:

Contact fields

GET /v1/contacts/fields

Company fields

GET /v1/companies/fields Each field object includes:

Field	Meaning
`id`	Exact field name to use in prompts and `fields` query params
`label`	Human-readable label
`fieldType`	`STANDARD`, `AI_VARIABLE`, `CRM_FIELD`, `FORMULA_FIELD`, or `EMPTY_FIELD`
`dataType`	Underlying data type
`editable`	Whether the entity update endpoint accepts this field
`promptReference`	Copy-paste-ready placeholder, for example `{firstName}`

For contact variables, GET /v1/contacts/fields includes both contact-backed placeholders and company-backed placeholders that are valid in contact prompts, such as {companyName}.

AI Messages, AI Snippets, and Message Templates

Workspaces migrated to the split AI-entity model (all endpoints below return 403 otherwise) manage outreach entities separately from AI research:

AI messages: GET|POST /v1/ai-variables/ai-messages, GET|PATCH|DELETE /v1/ai-variables/ai-messages/{aiMessageId}
AI snippets: GET|POST /v1/ai-variables/ai-snippets, GET|PATCH|DELETE /v1/ai-variables/ai-snippets/{aiSnippetId}
Message templates: GET|POST /v1/ai-variables/message-templates, GET|PATCH|DELETE /v1/ai-variables/message-templates/{messageTemplateId}
Tones: GET /v1/ai-variables/ai-message-tones — AI messages and snippets require a toneId; use this endpoint to discover valid IDs (workspace-owned plus Enginy defaults)

Prompt token syntax

Prompts are plain text with strictly validated tokens:

{fieldId} for contact/company/CRM/formula/notes fields — the same IDs the field-discovery endpoints return
{aiResearch:<id-or-name>}, {aiSnippet:<id-or-name>}, {aiMessage:<id-or-name>} for AI entity references
{{ and }} escape literal braces

Unknown or ambiguous tokens fail with 400; the response details.issues lists each problem and details.validTokenSample shows tokens that would be valid. When a referenced entity name is shared by several entities, the error lists the candidate IDs — retry with {aiSnippet:<id>}. Reference policy per entity type: AI messages may reference AI research and other AI messages; AI snippets may reference AI research only; message templates may embed AI snippets and AI research. Read responses include prompts both as rich text (promptRichText / messagesRichText) and as round-trippable plain text (prompt / messages / subject) in the same token syntax, so you can fetch, edit, and resubmit.

Typical Flow

Call GET /v1/contacts/fields or GET /v1/companies/fields
Build your prompt with the returned field id values
Create the AI Variable with POST /v1/ai-variables
Retrieve contacts or companies with the generated field through the normal entity endpoints

Notes

Archived AI Variables are excluded from GET /v1/ai-variables unless you pass includeArchived=true
Updating prompt causes Enginy to regenerate its internal prompt representation automatically
Deleting an AI Variable also removes its generated smart-field values from entity records

​Overview

​Mental Model

​Prompt Format

​Request Format

​Minimal create payload

​Structured create payload

​AI Variable Fields

​outputSchema Format

​search Toggle

​Folder Endpoints

​Discovering Valid Field Names

​Contact fields

​Company fields

​AI Messages, AI Snippets, and Message Templates

​Prompt token syntax

​Typical Flow

​Notes