Date Custom Field

Date custom fields allow you to store single dates or date ranges for records. They support timezone handling, intelligent formatting, and can be used to track deadlines, event dates, or any time-based information.

Basic Example

Create a simple date field:

mutation CreateDateField {
  createCustomField(input: {
    name: "Deadline"
    type: DATE
  }) {
    id
    name
    type
  }
}

Advanced Example

Create a due date field with description:

mutation CreateDueDateField {
  createCustomField(input: {
    name: "Contract Expiration"
    type: DATE
    isDueDate: true
    description: "When the contract expires and needs renewal"
  }) {
    id
    name
    type
    isDueDate
    description
  }
}

Input Parameters

CreateCustomFieldInput

Note: Custom fields are automatically associated with the project based on the user’s current project context. No projectId parameter is required.

Setting Date Values

Date fields can store either a single date or a date range:

Single Date

mutation SetSingleDate {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    startDate: "2025-01-15T10:00:00Z"
    endDate: "2025-01-15T10:00:00Z"
    timezone: "America/New_York"
  }) {
    id
    customField {
      value  # Contains { startDate, endDate, timezone }
    }
  }
}

Date Range

mutation SetDateRange {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    startDate: "2025-01-01T09:00:00Z"
    endDate: "2025-01-31T17:00:00Z"
    timezone: "Europe/London"
  }) {
    id
    customField {
      value  # Contains { startDate, endDate, timezone }
    }
  }
}

All-Day Event

mutation SetAllDayEvent {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    startDate: "2025-01-15T00:00:00Z"
    endDate: "2025-01-15T23:59:59Z"
    timezone: "Asia/Tokyo"
  }) {
    id
    customField {
      value  # Contains { startDate, endDate, timezone }
    }
  }
}

SetTodoCustomFieldInput Parameters

Note: If only startDate is provided, endDate automatically defaults to the same value.

Date Formats

ISO 8601 Format

All dates must be provided in ISO 8601 format:

• 2025-01-15T14:30:00Z - UTC time
• 2025-01-15T14:30:00+05:00 - With timezone offset
• 2025-01-15T14:30:00.123Z - With milliseconds

Timezone Identifiers

Use standard timezone identifiers:

• America/New_York
• Europe/London
• Asia/Tokyo
• Australia/Sydney

If no timezone is provided, the system defaults to the user’s detected timezone.

Creating Records with Date Values

When creating a new record with date values:

mutation CreateRecordWithDate {
  createTodo(input: {
    title: "Project Milestone"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "date_field_id"
      value: "2025-02-15"  # Simple date format
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # Date values are accessed here
      }
    }
  }
}

Supported Input Formats

When creating records, dates can be provided in various formats:

Response Fields

TodoCustomField Response

Important: Date values (startDate, endDate, timezone) are accessed through the customField.value field, not directly on TodoCustomField.

Value Object Structure

Date values are returned through the customField.value field as a JSON object:

{
  "customField": {
    "value": {
      "startDate": "2025-01-15T10:00:00.000Z",
      "endDate": "2025-01-15T17:00:00.000Z",
      "timezone": "America/New_York"
    }
  }
}

Note: The value field is on the CustomField type, not on TodoCustomField.

Querying Date Values

When querying records with date custom fields, access the date values through the customField.value field:

query GetRecordWithDateField {
  todo(id: "todo_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # For DATE type, contains { startDate, endDate, timezone }
      }
    }
  }
}

The response will include the date values in the value field:

{
  "data": {
    "todo": {
      "customFields": [{
        "customField": {
          "name": "Deadline",
          "type": "DATE",
          "value": {
            "startDate": "2025-01-15T10:00:00.000Z",
            "endDate": "2025-01-15T10:00:00.000Z",
            "timezone": "America/New_York"
          }
        }
      }]
    }
  }
}

Date Display Intelligence

The system automatically formats dates based on the range:

All-day detection: Events from 00:00 to 23:59 are automatically detected as all-day events.

Timezone Handling

Storage

• All dates are stored in UTC in the database
• Timezone information is preserved separately
• Conversion happens on display

Best Practices

• Always provide timezone for accuracy
• Use consistent timezones within a project
• Consider user locations for global teams

Common Timezones

Filtering and Querying

Date fields support complex filtering:

query FilterByDateRange {
  todos(filter: {
    customFields: [{
      customFieldId: "date_field_id"
      dateRange: {
        startDate: "2025-01-01T00:00:00Z"
        endDate: "2025-12-31T23:59:59Z"
      }
      operator: EQ  # Returns todos whose dates overlap with this range
    }]
  }) {
    id
    title
  }
}

Checking for Empty Date Fields

query FilterEmptyDates {
  todos(filter: {
    customFields: [{
      customFieldId: "date_field_id"
      values: null
      operator: IS  # Returns todos with no date set
    }]
  }) {
    id
    title
  }
}

Supported Operators

Required Permissions

Error Responses

Invalid Date Format

{
  "errors": [{
    "message": "Invalid date format. Use ISO 8601 format",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Field Not Found

{
  "errors": [{
    "message": "Custom field not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

Limitations

• No recurring date support (use automations for recurring events)
• Cannot set time without date
• No built-in working days calculation
• Date ranges don’t validate end > start automatically
• Maximum precision is to the second (no millisecond storage)

Related Resources

• Custom Fields Overview - General custom field concepts
• Automations API - Create date-based automations