Skip to main content
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 retrieval endpoint always returns them in aiFields, and the deal retrieval endpoint returns them when called with returnAiFields. 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; for recordings and deals, start a generation for them. Creating, updating, archiving and generating 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. 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.

​
Generations

A generation produces the values of a field for a set of records, like the generate button in the app. Start it with the generations endpoint of the field, targeting either a list of identifiers (recordingIds or dealIds) or the records of a view (viewId). Values are generated asynchronously: the endpoint returns a generationId to follow the generation progress and to cancel it. By default, the FillMissing mode only processes the records without a value. The Recompute mode regenerates every record. Recording generations only process the recordings with a ready transcript that the generation author can edit. A single generation covers at most 1,000 recordings or 333 deals. Larger generations are rejected, never truncated. Identifier lists have the same limit, so a longer list is rejected upfront, even when most of its records already have a value: use viewId for larger sets. A generation is also rejected when the field is manual (it has no prompt). Set estimateOnly to get the record count and estimatedCredits without starting the generation. An estimate performs the same checks, so it fails whenever the real generation would. The status of a generation is Pending while it is in progress, Ready once it has finished and Failed when it failed or was canceled. Canceling a generation keeps the values already generated. Like field creation, starting a generation requires a creatorEmail: it must belong to an active workspace member other than a Guest, who becomes the generation author.