Data Records

Tags: data, records

Structured data record CRUD within a data type

In the product: Forms

Resources

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

CreateDataRecordRequest

Field	Type	Required	Description
assignmentTaskId	Integer
externalId	String
fieldValues	dict[str, Any]	✓
memberExternalId	String
memberId	Integer

Example:

{
  "fieldValues": {}
}

DataRecordResponse

Field	Type	Required	Description
accessMode	Integer
createdAt	DateTime	✓
dataTypeId	Integer	✓
externalId	String
fieldValues	Dict[str, Any]	✓
id	Integer	✓
memberId	Integer	✓
memberName	String
retirement	DataRecordRetirementResponse | null
updatedAt	DateTime	✓
uuid	UUID	✓

Example:

{
  "id": 0,
  "uuid": "00000000-0000-0000-0000-000000000000",
  "dataTypeId": 0,
  "memberId": 0,
  "fieldValues": {},
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

DataRecordRetirementResponse

Field	Type	Required	Description
reason	Literal['monday_item_archived', 'monday_item_deleted']	✓
source	Literal['monday']		Default: monday
status	Literal['retired']		Default: retired

Example:

{
  "status": "retired",
  "reason": "monday_item_archived",
  "source": "monday"
}

MemberRecordCountsResponse

Field	Type	Required	Description
counts	dict[int, int]	✓

Example:

{
  "counts": {}
}

UpdateDataRecordRequest

Field	Type	Required	Description
assignmentTaskId	Integer
externalId	String
fieldValues	dict[str, Any]	✓
memberExternalId	String
memberId	Integer

Example:

{
  "fieldValues": {}
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/data-types/member-record-counts - Member Record Counts
• POST /api/v2/w/{workspace_uuid}/data-types/{data_type_id}/records - Records
• DELETE /api/v2/w/{workspace_uuid}/data-types/{data_type_id}/records/{record_id} - Delete Records
• PUT /api/v2/w/{workspace_uuid}/data-types/{data_type_id}/records/{record_id} - Update Records

Member Record Counts

GET /api/v2/w/{workspace_uuid}/data-types/member-record-counts

Description:

Get record counts per data type for a specific member.

Returns the number of records each data type has for the specified member. This is more efficient than querying each data type individually.

Query Parameters:

• member_id: The member ID to get record counts for

Response: Returns an object with counts mapping data type IDs to record counts.

Permissions: Self-access: Any authenticated member can query their own record counts. Cross-member access: Only returns counts for data types where the caller has list_all permission (same model used by other record read endpoints).

Error Responses:

• 401 Unauthorized: Missing or invalid authentication

Authorization: Requires datatypes:read scope

Parameters:

• member_id (Integer)

Response: See MemberRecordCountsResponse

---

Records

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

Description:

Create a new record for a data type.

Creates a new data record instance with field values conforming to the data type's schema. Field values are validated against the schema's type and validation rules before creation.

Path Parameters:

• data_type_id: Data type ID or slug to create a record for

Request Body:

• fieldValues: Object mapping field slugs to values
• memberId: Optional member ID to associate with the record
• externalId: Optional external system identifier
• assignmentTaskId: Optional assignment task ID linkage

Response: Returns the created DataRecordResponse object with all field values and metadata. From a Site session, on a Form that allows one record per member, a Member who already has a record gets that record back, updated with the submitted fields.

Permissions: Self-access: Users can create their own records (memberId = self). Admin access: RECORDS_WRITE scope required to create records for other members.

Error Responses:

• 400 Bad Request: Invalid field values or validation error
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: User lacks create permission for this data type
• 404 Not Found: Data type not found

Related Endpoints:

• GET /data-types/{id}/records - List all records
• POST /data-types/{id}/upsert/{external_id} - Create or update by external ID
• PUT /data-types/{id}/records/{record_id} - Update a record

Authentication: Requires workspace member

Parameters:

• data_type_id (String)
• record (CreateDataRecordRequest)

Response: See DataRecordResponse

---

Delete Records

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

Description:

Delete a data record.

The record is TOMBSTONED, not erased: deleted_at is set so the record stops appearing in every ordinary read, while the row and its DataRecordUpdate change history are RETAINED. Retaining the audit trail is the point — a normal admin delete must not erase it. The deletion itself is recorded as a PHI_DATA_DELETED compliance event (IDs only).

This is therefore NOT a purge, and it is not a mechanism for erasing stored values on request. The only purge in the product is the operator's orphan-inventory -> orphan-backfill pair (see data_types_lifecycle).

Because uniqueness on external_id is enforced only over live rows (uq_data_record_type_external_id_live), the deleted record's external id becomes reusable immediately.

Path Parameters:

• data_type_id: Data type ID the record belongs to
• record_id: Record ID to delete

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

Permissions: Requires delete permission for the data type or record member access.

Error Responses:

• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: User lacks delete permission
• 404 Not Found: Record not found

Related Endpoints:

• GET /data-types/{data_type_id}/records/{record_id} - View record before deletion
• GET /data-types/{data_type_id}/records - List remaining records

Authorization: Requires records:admin scope

Parameters:

• data_type_id (Integer)
• record_id (Integer)

Response: dict[str, str]

---

Update Records

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

Description:

Update an existing data record.

Modifies field values in a data record, creating an audit trail entry for the change. Only specified fields are updated; omitted fields retain their current values. Values are validated against the data type's schema.

Path Parameters:

• data_type_id: Data type ID the record belongs to
• record_id: Record ID to update

Request Body:

• fieldValues: Object mapping field slugs to new values (partial updates supported)

Response: Returns the updated DataRecordResponse object with all current field values.

Permissions: Self-access: Users can update records where they are the member. Admin access: RECORDS_WRITE scope required to update other members' records.

Error Responses:

• 400 Bad Request: Invalid field values or validation error
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: User lacks write permission
• 404 Not Found: Record not found

Related Endpoints:

• GET /data-types/{data_type_id}/records/{record_id} - Get current record state
• GET /data-types/{data_type_id}/records/{record_id}/changes - View update history
• DELETE /data-types/{data_type_id}/records/{record_id} - Delete the record

Authentication: Requires workspace member

Parameters:

• data_type_id (Integer)
• record_id (Integer)
• record_update (UpdateDataRecordRequest)

Response: See DataRecordResponse

---