Field Types Reference

Understanding Field Types and Formats

Different field types require specific data formats when creating or updating records via the API. This reference guide shows you exactly how to format data for each field type.

Simple Text Fields

Number Fields

Boolean Fields

// This explicitly sets it to checked
{"is_active": 1}

// This omits it - will be set to 0 (unchecked)
{}

Date and Time Fields

Calendar (Date Range)

Calendar fields store a start and end date. Use the field slug with __start and __end suffixes:

{
  "event_date__start": "2024-01-27",
  "event_date__end": "2024-01-29"
}

Complex Field Types

Name Field

Name fields have multiple sub-components. Use brackets to specify each part:

{
  "full_name[title]": "Dr.",
  "full_name[first_name]": "John",
  "full_name[middle_name]": "C",
  "full_name[last_name]": "Doe"
}

You can omit optional parts:

{
  "full_name[first_name]": "John",
  "full_name[last_name]": "Doe"
}

Address Field

Address fields have multiple components for full addresses:

{
  "address[address]": "123 Main Street",
  "address[address2]": "Apt 4B",
  "address[city]": "New York",
  "address[state]": "NY",
  "address[zip]": "10001",
  "address[country]": "USA"
}

Selection Fields

Select, Radio, Dropdown (Single Choice)

Use the option value as a string:

{
  "status": "active"
}

To find valid option values, use the /full-fields-info endpoint:

GET /api/v1/data-tables/{tableId}/full-fields-info

Multi-Select and Checkbox (Multiple Choice)

Use an array of values:

{
  "interests": ["sports", "music", "travel"]
}

Or as form-data:

interests[]=sports&interests[]=music&interests[]=travel

Connection (Join) Fields

Connection fields link to records in other tables.

One-to-One Connection

Use a single record ID:

{
  "assigned_to": "encoded_user_id"
}

One-to-Many Connection

Use an array of record IDs:

{
  "team_members": ["encoded_id_1", "encoded_id_2", "encoded_id_3"]
}

Or comma-separated:

{
  "team_members": "encoded_id_1,encoded_id_2,encoded_id_3"
}

Or as form-data:

team_members[]=id1&team_members[]=id2&team_members[]=id3

Reading Connection Field Values

When retrieving records with connection fields, the API returns both IDs and display values:

{
  "assigned_to": ["encoded_user_id"],
  "assigned_to_val": [
    {
      "id": "encoded_user_id",
      "val": "John Doe"
    }
  ]
}

• assigned_to - Array of connected record IDs
• assigned_to_val - Array of objects with ID and display value

File Upload

File uploads require multipart/form-data content type:

POST /api/v1/data-tables/{tableId}/records

Content-Type: multipart/form-data

file_field: [file upload]
first_name: John
last_name: Doe

Using curl

curl --location 'https://api.tadabase.io/api/v1/data-tables/lGArg7rmR6/records' \
--header 'X-Tadabase-App-id: your_app_id' \
--header 'X-Tadabase-App-Key: your_app_key' \
--header 'X-Tadabase-App-Secret: your_app_secret' \
--form 'file_field=@"/path/to/file.pdf"' \
--form 'first_name="John"' \
--form 'last_name="Doe"'

Field Behavior When Omitted

When you omit a field from an API request, it will be set to an empty/null value:

Complete Example: Creating a Record with All Field Types

POST /api/v1/data-tables/lGArg7rmR6/records

Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "555-123-4567",
  "age": 30,
  "salary": 75000.50,
  "is_active": 1,
  "start_date": "2024-01-15",
  "meeting_time": "14:30:00",
  "last_login": "2024-01-27 09:15:00",
  "full_name[first_name]": "John",
  "full_name[last_name]": "Doe",
  "address[address]": "123 Main St",
  "address[city]": "New York",
  "address[state]": "NY",
  "address[zip]": "10001",
  "status": "active",
  "interests": ["sports", "reading"],
  "assigned_to": "user_id_here",
  "team_members": ["id1", "id2"],
  "notes": "This is a long text field",
  "description": "
This is rich text
"
}

Getting Field Information

To see what fields are available in a table and their types:

Basic Field List

GET /api/v1/data-tables/{tableId}/fields

Returns:

{
  "type": "success",
  "fields": [
    {
      "slug": "first_name",
      "name": "First Name",
      "type": "Text"
    },
    {
      "slug": "status",
      "name": "Status",
      "type": "Select"
    }
  ]
}

Full Field Information

GET /api/v1/data-tables/{tableId}/full-fields-info

Returns detailed information including options, validation rules, and relationships:

{
  "fields": [
    {
      "slug": "status",
      "fieldId": "field_40",
      "name": "Status",
      "type": "Select",
      "description": "Customer status",
      "default_value": "pending",
      "is_unique": "No",
      "options": [
        {"label": "Pending", "value": "pending"},
        {"label": "Active", "value": "active"},
        {"label": "Inactive", "value": "inactive"}
      ]
    }
  ]
}

Best Practices

1. Always Include Required Fields: Check which fields are required before creating records
2. Explicitly Set Values: Don't rely on default values - set all fields explicitly via API
3. Validate Data First: Validate data in your application before sending to API
4. Use Correct Formats: Follow the exact format required for each field type
5. Get Field Info First: Use /fields or /full-fields-info to understand field structure
6. Handle Unique Fields: Check for existing records before creating if fields have unique constraints

Next Steps

Learn how to work with data tables and fields programmatically:

→ Tables and Fields API

Discover how to list tables, get field information, and understand table structure via the API.