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

Mental Model

An AI Variable is defined by the prompt you write, the entity it belongs to, and the output format you expect back. 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. 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` \| `url` \| `email`	Required
`values`	string[]	Required when `type` is `oneOf`. 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

AI Variables support folder CRUD for both 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}

Deleting an AI Variable folder does not delete the AI Variables inside it. Enginy moves those variables, 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}.

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

​Typical Flow

​Notes