Skip to main content

​
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

FieldTypeRequiredNotes
namestringyes on createMust be unique per entity
entityCONTACT | COMPANYyes on createDetermines where the generated value is stored
promptstringyes on createPlain-text prompt template
modelstring | nullnoOptional model ID
outputSchemaobjectnoDefaults to { "type": "text", "provideExplanation": false }
searchbooleannoDeep Search toggle. true enables Deep Search, false disables it
folderIdnumber | nullnoFolder used for organization. Use the AI Variable folder endpoints to discover or manage folder IDs
customWebsiteFieldstring | nullnoOptional custom website field source

​
outputSchema Format

outputSchema describes the expected AI output.
FieldTypeNotes
typetext | number | date | oneOf | url | emailRequired
valuesstring[]Required when type is oneOf. Requests fail validation if this array is missing or empty
provideExplanationbooleanOptional
jsonSchemaJSON valueOptional 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:
FieldMeaning
idExact field name to use in prompts and fields query params
labelHuman-readable label
fieldTypeSTANDARD, AI_VARIABLE, CRM_FIELD, FORMULA_FIELD, or EMPTY_FIELD
dataTypeUnderlying data type
editableWhether the entity update endpoint accepts this field
promptReferenceCopy-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

  1. Call GET /v1/contacts/fields or GET /v1/companies/fields
  2. Build your prompt with the returned field id values
  3. Create the AI Variable with POST /v1/ai-variables
  4. 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