An AIRecommendation entity represents an AI-generated suggestion provided to a specific target. The recommendation includes actions, context, display details, and metadata about its category, priority, execution policy, and lifecycle status.
Properties
Name
Description
Type
Required
uid
A unique identifier for the recommendation.
string
Yes
producer
Upstream agent or partner system that produced this recommendation (for example: client_agent, lead_capture_agent, partner_x).
string
business_uid
The unique identifier (UID) of the business that owns this recommendation. Automatically set based on the authenticated token.
string
created_at
The timestamp when the recommendation was created, in ISO 8601 format.
string
updated_at
The timestamp when the recommendation was last updated, in ISO 8601 format.
string
category
Recommendation category set by the producer for interface use: needs_attention (time-sensitive and requires the user's attention) or opportunity (growth-focused value opportunity that does not require immediate action).
string (enum: needs_attention, opportunity)
priority
Relative ordering priority within the same category: high (higher priority, surfaced first) or standard (default priority).
string (enum: high, standard)
execution_policy
Indicates whether this recommendation is auto-executed by an agent or requires human review: auto_execute (may be executed automatically by the system or an authorized agent) or requires_human_approval (must be reviewed and approved by a human before execution).
Contains display-related information for the recommendation.
object
Yes
context
The context in which the recommendation was generated.
object
Yes
target
The target entity for this recommendation, typically representing the user or business involved.
object
Yes
status
Current lifecycle status of this recommendation, including the source of the latest status update.
object
Yes
Display Properties
Name
Description
Type
Required
title
A human-readable title describing the recommendation.
string
Context Properties
Name
Description
Type
Required
context_uid
A unique identifier for the context associated with this recommendation.
string
context_type
The type of context (e.g., matter, client, business).
string (enum: matter, client, business)
context_name
The display name of the context object (referenced by context_uid) this recommendation is about, according to its context_type — for example, the client's name when context_type is client (e.g., John Smith).
string
Target Properties
Name
Description
Type
Required
target_actor_uid
A unique identifier for the target actor (e.g., a user or business).
string
target_actor_type
The type of target actor (e.g., staff, directory).
string (enum: staff, directory)
Status Properties
Name
Description
Type
Required
state
Lifecycle state of the recommendation: active (available and not yet completed), completed (executed successfully or otherwise resolved), dismissed (explicitly dismissed without resolving the underlying need), approved (approved by the user but not yet at a terminal outcome), or snoozed (deferred to a later time or trigger condition).
