1. API
  2. Records
  3. Record types

Record types: Update

Last updated Open markdown version

Description

Update an existing record type. You can update the record type name, editable status, TTL settings, retention column, FIFO behavior, custom record limit, and fields.

See the Get Record Type API to learn more about record types.

Request

HTTP Method: PUT

Path parameter Description
record_type_id The ID of the record type to update.
Body parameter Description
name Optional The record type name.
description Optional A short description of the record type.
editable Optional Whether the records for this record type are editable or not.
ttl_days Optional Records for this record type will be deleted after this number of days. Accepted values: 0.25 (6 hours), 0.5 (12 hours), 1, 2, 3, 7, 14, 30, 60, 90, 180, 365, 548, 730, 1095, 1460, 1825, 2190, 2555, 2920, 3285, 3650.
retention_column_name Optional The timestamp column used to determine record age for TTL expiry. Accepted values are CREATED_AT and UPDATED_AT. With UPDATED_AT, a record's age resets each time it's updated, so only records that haven't been updated within ttl_days are deleted. Has no effect unless ttl_days is set. Sending null while TTL is set returns 400.
on_limit_reached Optional Behavior when the record type reaches its per-type record limit. Accepted values are REJECT (block new writes) and EVICT_OLDEST (delete the oldest record to make room).
max_records_limit Optional Custom per-record-type record limit. Must be a positive integer no greater than the tenant ceiling. Send null to clear an existing custom limit and fall back to the tenant default.
fields Optional An array of objects describing the record fields. See Fields parameter for behavior. Field-level description can also be updated.
field_ids_to_delete Optional An array of field IDs to delete. Use this to explicitly remove fields from the record type. Built-in default fields cannot be deleted.

Fields parameter

The fields parameter is an array of objects representing the record fields. When provided, fields included in the array are created or updated. Fields not included in the array are preserved unchanged. If the fields parameter is omitted, not provided, or set to null, all existing fields remain unchanged. Providing an empty array ([]) will also preserve all existing fields.

To update an existing field, include its id along with the properties to change. To add a new field, omit the id and provide at least a name and result_type. A record type can have at most 50 custom fields.

To delete fields, use the field_ids_to_delete parameter with an array of field IDs to remove.

Each field object accepts:

Field property Description
id Required to update an existing field; omit to create a new one.
name The field name.
result_type The field's data type: TEXT, NUMBER, TIMESTAMP, BOOLEAN, TEXT_ENUM, or ARTIFACT. Changing result_type on an existing field is only allowed between TEXT and TEXT_ENUM.
fixed_values Required for TEXT_ENUM, otherwise omit. Array of allowed values (max 100 entries).
description Optional A short description of the field. 
# Update only the record type name
curl -X PUT \
  https://<tenant-domain>/api/v1/record_types/<<record_type_id>> \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
      "name": "Updated record type name"
    }'

# Update fields
curl -X PUT \
  https://<tenant-domain>/api/v1/record_types/<<record_type_id>> \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
      "name": "Updated record type name",
      "description": "Updated description of the record type",
      "editable": true,
      "ttl_days": 7,
      "retention_column_name": "UPDATED_AT",
      "on_limit_reached": "EVICT_OLDEST",
      "max_records_limit": 5000,
      "fields": [
        {
          "id": 1,
          "name": "Updated Column Name",
          "result_type": "TEXT_ENUM",
          "fixed_values": ["Option A", "Option B", "Option C"]
        },
        {
          "name": "New Column",
          "result_type": "NUMBER"
        }
      ],
      "field_ids_to_delete": [2, 5]
    }'

Response

A successful request will return a JSON object representing the updated record type.

Field description

Parameter Description
id The record type ID.
name The record type name.
description A short description of the record type, or null if not set.
team_id ID of team to which the record type belongs.
editable Whether the records for this record type are editable or not.
ttl_days Records for this record type will be deleted after this number of days.
retention_column_name The timestamp column used to determine record age for TTL expiry. One of CREATED_AT or UPDATED_AT. With UPDATED_AT, a record's age resets each time it's updated.
on_limit_reached Behavior when the record type reaches its per-type record limit. One of REJECT (block new writes) or EVICT_OLDEST (delete the oldest record to make room).
max_records_limit Custom per-record-type record limit, or null if no custom limit is set (in which case the tenant default applies).
record_fields An array of objects describing the custom record fields defined by the user.
default_record_fields An array of objects describing the built-in default record fields.

Sample response

{
  "id": 1,
  "name": "Updated record type name",
  "description": "Updated description of the record type",
  "team_id": 123,
  "editable": true,
  "ttl_days": 7,
  "retention_column_name": "UPDATED_AT",
  "on_limit_reached": "EVICT_OLDEST",
  "max_records_limit": 5000,
  "record_fields": [
    {
      "id": 1,
      "name": "Updated Column Name",
      "description": null,
      "result_type": "TEXT_ENUM",
      "fixed_values": ["Option A", "Option B", "Option C"]
    },
    {
      "id": 6,
      "name": "New Column",
      "description": null,
      "result_type": "NUMBER",
      "fixed_values": []
    }
  ],
  "default_record_fields": [
    {
      "id": 2,
      "name": "Record ID",
      "description": null,
      "result_type": "NUMBER",
      "fixed_values": []
    },
    {
      "id": 3,
      "name": "Story name",
      "description": null,
      "result_type": "TEXT",
      "fixed_values": []
    },
    {
      "id": 4,
      "name": "Timestamp",
      "description": null,
      "result_type": "TIMESTAMP",
      "fixed_values": []
    },
    {
      "id": 5,
      "name": "Updated at",
      "description": null,
      "result_type": "TIMESTAMP",
      "fixed_values": []
    }
  ]
}
Was this helpful?