> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI fields

AI fields are the custom AI columns users define in Claap. An AI field is a
prompt with a typed output, evaluated by AI against the underlying activity:
the transcript of each recording, or the recordings and emails of each deal or
company. Company activity covers the recordings and emails linked to the
company itself as well as those of all its deals.

Each domain has its own set of endpoints under `/v1/recordings/fields`,
`/v1/deals/fields` and `/v1/companies/fields`. A created field joins the
workspace AI field library and can be used as a view column: its `fieldId`
matches the `fieldId` of the `AiSection` columns returned by the view
listing endpoints and accepted by the view create and update endpoints.

For recordings and deals, the generated values themselves are also available:
the recording and deal retrieval endpoints return the value of each AI field
when called with `returnAiFields`. Companies have no retrieval endpoint, so
company AI field values cannot be read through the API.

A field is evaluated as new activity comes in: values are generated for new
recordings, and for deals and companies when their activity changes. Creating
or updating a field does not generate values for existing recordings, deals or
companies. Creating, updating and archiving AI fields requires a workspace
plan that includes them; on other plans these endpoints fail with a
`forbidden` error. Listing and retrieving AI fields is available on all plans.

## Output types

The `outputType` attribute defines the type of value the AI produces. In
create and update requests it is nested with the other prompt attributes
(`prompt`, `coloredSelectOptions`, `hasTimecodes`, `ratingScale`) under the
`prompt` object; in the returned `AiField` object, these attributes appear at
the top level.

| Output type   | Output                                                        |
| ------------- | ------------------------------------------------------------- |
| `ActionList`  | A list of action items                                        |
| `Checkbox`    | A yes/no value                                                |
| `Date`        | A date                                                        |
| `List`        | A list of items, optionally linked to the recording timecodes |
| `MultiSelect` | One or more options from `coloredSelectOptions`               |
| `Numeric`     | A number                                                      |
| `Paragraph`   | A short text                                                  |
| `Rating`      | A rating between 1 and `ratingScale` (5 by default)           |
| `RichText`    | A formatted text                                              |
| `Select`      | A single option from `coloredSelectOptions`                   |

The `Select` and `MultiSelect` output types require `coloredSelectOptions`,
the list of options the AI can choose from. `hasTimecodes` only applies to the
`List` output type, and `ratingScale` only applies to the `Rating` output
type; they are ignored for other output types.

A generated `Rating` value is more than the number: the Markdown answer
starts with the rating (e.g. `4/5`) followed by a short justification with a
**Proof** section (the decisive evidence for the rating) and a **Gap** section
(what is missing to reach the next level, omitted when the rating is at its
maximum).

## Creator

Since API requests do not impersonate workspace users, creation endpoints
require a `creatorEmail` attribute. It must be the email address of an active
workspace member, who becomes the field author. When the workspace is
configured so that only Admins can create AI fields, the creator must be a
workspace Admin.

## CRM mapping

Recording and deal AI fields can be mapped to a CRM property with the
`crmField` attribute, so that generated values are pushed to the connected
CRM. The property is identified by its entity and name, and is validated
against the connected CRM: the property must exist, its type must be
compatible with the output type, and for select properties the
`coloredSelectOptions` values must match the CRM property options. Company AI
fields cannot be mapped to a CRM property.

## Updates

The update endpoints perform a full replace: always send the complete field
definition, as an omitted `crmField` is cleared.

## Archiving

AI fields cannot be deleted through the API, only archived. Archiving a field
removes it from the views that use it as a column and sets its `archivedAt`
attribute. Archived fields are excluded from the listing endpoints unless
`includeArchived` is set.