Activities Data Model
Audience: Technical Builders, Implementors, and Developers
Purpose: Explains the Activity data model in order to build integrations, automations, and workflows that depend on Activity data.
Overview
Activities represent work that has happened as Logged Activities or work that needs to happen as Scheduled Activities. Activities can be linked to Contacts or Custom Objects, appear on Timelines, and trigger or be triggered by Automations.
This page defines the Activities data model in Kizen, including the schemas, fields, and relationships used for scheduling and automating Activities.
Use this page when building:
Integrations that read or write Activity data
Automations that schedule Activities
Custom workflows that link Activities to Contacts or Custom Objects
The material on this page builds on information covered on the Activities Core Concepts page.
How Activities Are Identified
Kizen uses different unique IDs for Activity Objects, Scheduled Activities, and logged Activities. Each ID is unique within a Business and should not be reused across these resource types.
Activity Lifecycle
Activities transition through states derived from timestamps and relationships rather than explicit lifecycle enums.
Typical lifecycle progression:
Activity created
(If scheduled) due date reached
Activity completed
Logged Activity created (for Scheduled Activities)
Lifecycle state is inferred from fields such as:
due_datetimecompleted_atlogged_activity_idnotification
Kizen does not expose strict lifecycle enums such as “scheduled” or “completed”.
Data Structure
The Activity Model encompasses three core elements: Activity Objects, Schedule Activities, and Logged Activities.
The following diagram illustrates the lifecycle and structural relationships between these components:
An Activity Object defines the schema for a specific Activity type.
When work is planned, a Schedule Activity is create to track work that has not yet occurred.
When work is completed, or when an Activity is logged directly, a logged activity is created to capture the details of the engagement.
Activity Field Types
Activities in Kizen support three distinct categories of (fields[]) that behave differently at runtime depending on their type:
System fields: System-defined, non-modifiable fields that are included with every Activity.
Activity fields: Fields stored on the Activity itself. These fields are captured when an Activity is logged and do not update fields on associated Records.
Custom fields: Fields that belong to an associated Record on an Object. These fields are updated as part of Activity completion and apply only to logged Activities.
Understanding the difference between these field types is critical when designing Activity schemas, configuring required fields, and building workflows that update related Records.
System Fields
System fields are platform-defined fields that belong to the Activity itself. They are intrinsic to the Activity record and are included with every Activity.
Examples include:
Activity name
Description and Visibility
Completion timestamps
Built-in activity attributes
System fields:
Always belong to the Activity record
Are stored directly on the Activity Record
Cannot be modified or repurposed
Do not update fields on associated records when an Activity is completed
Activity Fields
Activity fields are fields defined on the Activity object itself that capture information specific to a logged Activity. These fields extend the Activity schema beyond system-defined attributes.
Examples include:
Outcome or result values
Activity-specific notes or classifications
Custom values captured at the time the Activity is logged
Activity fields:
Belong to Scheduled or Logged Activity records
Are stored directly on the Logged Activity
Are captured when an Activity is logged
Do not update fields on associated records when the Activity is completed
Activity fields are used to describe what happened during the Activity, not to modify related records.
Activity Custom Fields
Associated custom fields are fields that belong to a related object (such as a Contact or other Custom Object) and are updated only when the Activity is logged with a specific associated record selected.
These fields are included in the Activity experience, but their definitions come from the associated Record schema. When the Activity is completed, the values update the associated Record rather than the Activity.
Key characteristics:
Defined on the associated record and surface on the Activity only when a related Record is selected.
Use the field types supported by the associated object
Required only when a related Record is selected
Updated when the Activity is completed and logged
Do not apply if no associated Record is present
Associated Record fields allow Activities to drive updates to related records while keeping Activity data and Record data clearly separated.
(fields[]) Parameters
fields[]) Parametersid
UUID
Yes
Field definition ID
name
String
Yes
Canonical name
display_name
String
Yes
User-facing label
field_type
String
Yes
Base type
custom_field_type
String
Yes
Subtype
value
Object
No
Stored value
Record Associations
When an Activity is associated with a Contact or Custom Object, Activity custom fields may act on that associated Record and update it rather than only on the Activity itself.
A Record association gives you the ability to create Activity fields that update associated Records when an Activity is logged. These updates occur through configured Activity-to-object associations and do not change the Activity’s field model.
This behavior introduces important validation and permission considerations.
(associated_entities[]) Parameters
associated_entities[]) Parameterscustom_object_id
UUID
Yes
Object type for which the record belongs.
entity_id
UUID
Yes
ID of the linked record.
object_name
String
Yes
Object display name.
display_name
String
Yes
Record display name.
object_api_name
String
Yes
Canonical API name.
Activity Custom Field Population Behavior
When an associated Record is selected for an Activity:
Existing values from the associated Record are pre-filled into the corresponding Activity custom fields
This pre-fill occurs for Logged Activities with pre-selected associated Records
Pre-filled values bypass permissions only for existing values
For more information on permissions, see Activity Permissions.
Required Field Rules
All required fields behavior depends on the type of field you are creating or modifying and whether there is an associated record is selected for it.
Activity Custom Field Options
When creating an Activity custom field, Kizen gives you two option toggles on the fields.
If Field is Required is toggled on, the field will be always be required and this cannot be modified later. This applies even if no related entity is selected.
If the Informational Field is toggled on, the Activity custom field will be set to a read only status.
Activity Custom Field Advanced Rules
Sets the visibility permissions on the custom fields themselves with Activity. See: Advanced Activity Rules.
Required Associated Record Fields
When an Activity is associated with another record, any required fields on the associated record also become required for the Activity.
For example, if an Activity is associated with a Deal, the required Deal fields such as Owner or Stage will also be required and must be provided.
These fields are required only when a related Record is selected. If no related Record is associated, these fields are not required to submit the Activity.
Clearing Values
Users must be able to clear values from Activity custom fields during Activity submission, even when those fields were pre-filled from a related Record.
Clearing a value explicitly indicates intent and should be treated as a valid submission action.
Schemas
Activity Object Schema
Activity Objects define the type and configuration of Activities. All Scheduled and Logged Activities reference an Activities Object.
Scheduled Activity Schema
Scheduled Activities represent future tasks and can have an assignee and associations, but no field values.
Logged Activity Schema
Logged Activities represent past tasks and can have assignee and associations. While you cannot log an Activity via API, you can view logged records by ID.
Timeline Representation
Activities appear on Timelines based on associations and timestamps.
When Activities Appear
An Activity appears on a Timeline when it includes the record in associated_entities[]. If an Activity is associated to multiple records, it appears on each Timeline.
Lifecycle Impact
Completing a Scheduled Activity creates a Logged Activity, which appears on the Timeline at the appropriate chronological position.
If an association is removed or a record is archived, the Activity no longer appears on that Timeline.
Additional Information
What's Next?
Next, continue to Activity Permissions to understand how access to Activities is controlled, including:
Who can create, view, and modify Activities
How permissions interact with Activity Objects and associated records
How access rules are enforced consistently across the UI, APIs, and automations
Understanding permissions is essential before exposing Activity data through integrations or enabling automation workflows.
Last updated
Was this helpful?