Data Types

Tags: collections, data

Custom data type management

In the product: Forms

Resources

Request and response models used by the endpoints on this page.

CreateDataTypeRequest

Field	Type	Required	Description
adminOnly	Boolean		Default: False
description	String
eventRules	Array<EventRuleData> | null
fields	Array<SchemaField>
isCollection	Boolean		Default: False
name	String	✓
pinned	Boolean		Default: False
prompt	String
recordScope	<enum DataTypeRecordScope		Default: member
slug	String	✓
webhookEventsEnabled	Boolean		Default: False

Example:

{
  "name": "string",
  "slug": "string",
  "isCollection": false,
  "pinned": false,
  "webhookEventsEnabled": false,
  "recordScope": "member",
  "adminOnly": false
}

DataTypeResponse

Field	Type	Required	Description
accessMode	Integer
adminOnly	Boolean		Default: False
archived	Boolean		Default: False
categories	Array	✓
createdAt	DateTime	✓
description	String	✓
eventRules	Array<EventRuleResponse>	✓
fields	Array<SchemaField>	✓
id	Integer	✓
isCollection	Boolean	✓
name	String	✓
ownerId	Integer
pinned	Boolean
prompt	String	✓
recordCount	Integer
recordScope	String	✓
sensitivity	String	✓
slug	String	✓
updatedAt	DateTime	✓
uuid	String	✓
webhookEventsEnabled	Boolean		Default: False

Example:

{
  "id": 0,
  "name": "string",
  "uuid": "string",
  "slug": "string",
  "description": "string",
  "prompt": "string",
  "isCollection": false,
  "webhookEventsEnabled": false,
  "archived": false,
  "recordScope": "string",
  "adminOnly": false,
  "sensitivity": "string",
  "categories": [],
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "eventRules": [],
  "fields": []
}

EnumOption

Field	Type	Required	Description
label	String	✓	Display label shown to users
value	str	int	float
visibleWhen	String		CEL expression that must return true for this option to be visible. Uses record.data.<field_slug> syntax to reference other field values. CONSTRAINT: Can only reference non-FUNCTION fields.

Example:

{
  "label": "string",
  "value": "string"
}

EventRuleData

Field	Type	Required	Description
actionParams	dict[str, Any]		Parameters for the action
actionType	<enum EventRuleActionType	✓	The action type to execute
active	Boolean		Whether the rule is active (default: True)
conditions	String		CEL condition expression for conditional execution
delay	Integer		Delay in seconds before executing the action (default: 0)
eventType	<enum EventRuleEventType	✓	The event type that triggers this rule
name	String		Display name for the rule
objectType	EventRuleObjectType		The object type this rule applies to (inferred from parent if not provided)
triggerParams	dict[str, Any]		Parameters for the trigger (e.g., webhook config)
uuid	String	✓	UUID for matching/creating event rules

Example:

{
  "uuid": "string",
  "eventType": null,
  "actionType": null,
  "active": true,
  "delay": 0
}

EventRuleResponse

Field	Type	Required	Description
actionParams	Dict[str, Any]	✓
actionSetLocked	Boolean		Default: False
actionType	<enum EventRuleActionType	✓
active	Boolean	✓
appConnectionId	Integer
calendarEventTypeId	Integer	✓
calendarId	Integer	✓
celBlockedAt	DateTime
conditions	String	✓
createdAt	DateTime	✓
dataTypeId	Integer	✓
dataTypeName	String
delay	Integer	✓
error	String	✓
errorMessage	String	✓
eventType	<enum EventRuleEventType	✓
failedAt	DateTime	✓
id	Integer	✓
journeyId	Integer
journeyStepId	Integer	✓
name	String	✓
objectType	<enum EventRuleObjectType	✓
order	Integer	✓
routineId	Integer	✓
taskId	Integer	✓
taskName	String
taskWorkflowId	Integer
triggerParams	Dict[str, Any]	✓
updatedAt	DateTime	✓
uuid	String	✓
workflowRevisionId	Integer	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "objectType": null,
  "name": "string",
  "eventType": null,
  "conditions": "string",
  "actionType": null,
  "actionParams": {},
  "triggerParams": {},
  "active": false,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "taskId": 0,
  "dataTypeId": 0,
  "routineId": 0,
  "workflowRevisionId": 0,
  "calendarId": 0,
  "calendarEventTypeId": 0,
  "journeyStepId": 0,
  "error": "string",
  "errorMessage": "string",
  "failedAt": "2024-01-01T00:00:00Z",
  "delay": 0,
  "order": 0,
  "actionSetLocked": false
}

FieldRenameMapping

Field	Type	Required	Description
source	String	✓
target	String	✓

Example:

{
  "source": "string",
  "target": "string"
}

SchemaField

Field	Type	Required	Description
adminOnly	Boolean		Whether only admins can see this field (default: False)
categories	Array<Literal[personal, identifier, phi, credential]>		Regulatory or content categories for audit and policy
celFunction	String		CEL expression that computes this field's value. CONSTRAINT: Can ONLY reference regular fields (TEXT, NUMBER, DATE, etc.). Cannot reference other FUNCTION fields. Syntax: record.data.<field_slug>. Example: 'record.data.score1 + record.data.score2'
defaultValue	Any		Default value for the field
description	String		Optional field description
fieldType	Union[Literal[enum, email, phone, text, longtext, number, integer, boolean, date, datetime, time_of_day, us_zip_code, array, object, function], DataFieldType]		Field type (text, email, enum, etc.) (default: text)
name	String	✓	Display name for the field
options	Array<EnumOption> | null		Options for enum fields as {label, value} objects.
order	Integer		Deprecated: Display order is now determined by array position
referencedTypeId	Integer		Referenced DataType ID for reference fields
required	Boolean		Whether field is required (default: False)
sensitivity	Literal['public', 'internal', 'confidential', 'restricted', 'secret']		Disclosure severity for audit and access policy (default: confidential)
shouldIndex	Boolean		Whether to index this field (default: False)
slug	String	✓	Unique field identifier
validateCel	String		CEL expression for cross-field validation. Context: 'value' (current field value), 'record.data.<field_slug>' (other fields). Returns: true if valid, or a string error message if invalid. CONSTRAINT: Can only reference non-FUNCTION fields. Example: 'value >= record.data.min_score' or 'value < record.data.min_score ? "Must be >= " + string(record.data.min_score) : true'

Example:

{
  "slug": "string",
  "name": "string",
  "fieldType": "text",
  "required": false,
  "shouldIndex": false,
  "adminOnly": false,
  "sensitivity": "confidential"
}

UpdateDataTypeRequest

Field	Type	Required	Description
adminOnly	Boolean		Default: False
description	String
eventRules	Array<EventRuleData> | null
fields	Array<SchemaField> | null
isCollection	Boolean
name	String
ownerId	Integer
pinned	Boolean
prompt	String
recordScope	DataTypeRecordScope
renameFields	Array<FieldRenameMapping> | null
slug	String
webhookEventsEnabled	Boolean		Default: False

Example:

{
  "webhookEventsEnabled": false,
  "adminOnly": false
}

ValidateSlugRequest

Field	Type	Required	Description
excludeId	Integer
slug	String	✓

Example:

{
  "slug": "string"
}

ValidateSlugResponse

Field	Type	Required	Description
available	Boolean	✓
suggestedSlug	String

Example:

{
  "available": false
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/data-types - List
• POST /api/v2/w/{workspace_uuid}/data-types - Create
• GET /api/v2/w/{workspace_uuid}/data-types/slug/{slug} - Slug
• POST /api/v2/w/{workspace_uuid}/data-types/validate-slug - Validate Slug
• DELETE /api/v2/w/{workspace_uuid}/data-types/{data_type_id} - Delete Data Type Id
• GET /api/v2/w/{workspace_uuid}/data-types/{data_type_id} - Get Data Type Id
• PUT /api/v2/w/{workspace_uuid}/data-types/{data_type_id} - Update Data Type Id

List

GET /api/v2/w/{workspace_uuid}/data-types

Description:

List all data types in the workspace.

Retrieves all custom data type definitions created in the workspace, including their field schemas, record counts, and configuration. Data types define structured data models that can be used to store and organize workspace information.

Query Parameters:

• archived: Filter by archived status (boolean, default: false)

Response: Returns an array of DataTypeResponse objects, each containing the data type's ID, name, slug, description, fields (with types and validation rules), and record count.

Permissions: Requires authenticated member session. All workspace members can list data types.

Error Responses:

• 401 Unauthorized: Missing or invalid authentication

Related Endpoints:

• POST /data-types - Create a new data type
• GET /data-types/{data_type_id} - Get a specific data type
• GET /data-types/{data_type_id}/records - List records for a data type

Authorization: Requires datatypes:read scope

Parameters:

• archived (Boolean)
• sortBy (DataTypeSortField)
• sortOrder (SortOrder)

Response: List of DataTypeResponse

---

Create

POST /api/v2/w/{workspace_uuid}/data-types

Description:

Create a new custom data type.

Defines a new structured data model in the workspace with custom fields and validation rules. Data types can represent any entity (customers, products, tickets, etc.) and are used by assistants to store and retrieve structured information.

Request Body:

• name: Display name for the data type
• slug: URL-friendly identifier (auto-generated if not provided)
• description: Optional description of the data type's purpose
• fields: Array of field definitions with name, type, validation, and indexing options
• adminOnly: Hide the Form and its records from every Member without records:admin (default false)

Response: Returns the created DataTypeResponse object with all field definitions and configuration.

Permissions: Requires appropriate admin scope to create data types.

Error Responses:

• 400 Bad Request: Invalid request parameters or duplicate slug
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: User lacks appropriate admin scope
• 500 Internal Server Error: Database error during creation

Related Endpoints:

• GET /data-types - List all data types
• PUT /data-types/{data_type_id} - Update data type definition
• POST /data-types/{data_type_id}/records - Create records of this type

Authorization: Requires datatypes:write scope

Parameters:

• data_type (CreateDataTypeRequest)

Response: See DataTypeResponse

---

Slug

GET /api/v2/w/{workspace_uuid}/data-types/slug/{slug}

Description:

Get a data type by its slug identifier.

Retrieves complete data type details using its URL-friendly slug identifier. Returns the full schema including all field definitions, types, and validation rules.

Path Parameters:

• slug: URL-friendly slug identifier for the data type

Response: Returns a DataTypeResponse object with complete field schema and configuration.

Permissions: Requires authenticated member session.

Error Responses:

• 401 Unauthorized: Missing or invalid authentication
• 404 Not Found: Data type with specified slug not found

Related Endpoints:

• GET /data-types/{data_type_id} - Get data type by numeric ID
• GET /data-types - List all data types
• GET /data-types/{data_type_id}/records - Get records for this data type

Authorization: Requires datatypes:read scope

Parameters:

• slug (String)

Response: See DataTypeResponse

---

Validate Slug

POST /api/v2/w/{workspace_uuid}/data-types/validate-slug

Description:

Validate if a data type slug is available.

Checks if the given slug conflicts with existing data types and suggests a unique alternative if needed.

Request Body:

• slug: The slug to validate
• excludeId: Optional data type ID to exclude (for updates)

Response:

• available: Whether the slug is available
• suggestedSlug: A suggested unique slug if the original is taken

Permissions: Requires valid workspace membership.

Authorization: Requires datatypes:write scope

Parameters:

• request - See ValidateSlugRequest

Response: See ValidateSlugResponse

---

Delete Data Type Id

DELETE /api/v2/w/{workspace_uuid}/data-types/{data_type_id}

Description:

Permanently delete a data type and all its records.

Removes a data type definition along with all associated records and field indexes. This operation is irreversible and will delete all data stored in records of this type. Field indexes are removed via background tasks.

Path Parameters:

• id: Data type ID to delete

Response: Returns a status object with "deleted" confirmation.

Permissions: Requires appropriate admin scope to delete data types.

Error Responses:

• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: User lacks appropriate admin scope
• 404 Not Found: Data type not found
• 500 Internal Server Error: Database error during deletion

Related Endpoints:

• GET /data-types - List remaining data types
• POST /data-types/{data_type_id}/export - Export data before deletion
• GET /data-types/{data_type_id}/records - View records that will be deleted

Authorization: Requires datatypes:admin scope

Parameters:

• data_type_id (Integer)

Response: dict[str, str]

---

Get Data Type Id

GET /api/v2/w/{workspace_uuid}/data-types/{data_type_id}

Description:

Get detailed information about a specific data type.

Retrieves complete data type configuration including all field definitions, record count, and metadata. Includes field types, validation rules, and indexing status. This endpoint accepts either the numeric data type ID or stable UUID.

Path Parameters:

• data_type_id: Data type numeric ID or UUID to retrieve

Response: Returns a DataTypeResponse object with complete field schema, record count, and all configuration details.

Permissions: Requires authenticated member session.

Error Responses:

• 401 Unauthorized: Missing or invalid authentication
• 404 Not Found: Data type not found

Related Endpoints:

• GET /data-types/slug/{slug} - Get data type by slug
• PUT /data-types/{data_type_id} - Update data type
• GET /data-types/{data_type_id}/records - List records for this data type

Authorization: Requires datatypes:read scope

Parameters:

• data_type_id (String)

Response: See DataTypeResponse

---

Update Data Type Id

PUT /api/v2/w/{workspace_uuid}/data-types/{data_type_id}

Description:

Update an existing data type definition.

Modifies a data type's metadata, field definitions, or configuration. Can add new fields, update field properties, or modify validation rules. Existing records are preserved and automatically adapt to schema changes.

Path Parameters:

• id: Data type ID to update

Request Body:

• name: Updated display name (optional)
• description: Updated description (optional)
• fields: Updated field definitions array (optional)
• adminOnly: Hide the Form and its records from every Member without records:admin (optional; changing it needs the per-DataType admin action)

Response: Returns the updated DataTypeResponse object with refreshed schema and configuration.

Permissions: Requires appropriate admin scope to update data types.

Error Responses:

• 400 Bad Request: Invalid update parameters or validation error
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: User lacks appropriate admin scope
• 404 Not Found: Data type not found
• 500 Internal Server Error: Database error during update

Related Endpoints:

• GET /data-types/{data_type_id} - Get current data type definition
• DELETE /data-types/{data_type_id} - Delete the data type
• GET /data-types/{data_type_id}/records - View records affected by schema changes

Authorization: Requires datatypes:write scope

Parameters:

• data_type_id (Integer)
• data_type (UpdateDataTypeRequest)

Response: See DataTypeResponse

---