The phone column stores a phone number together with a country code.

Via the API, the phone column supports read, filter, update, and clear operations.

Queries

Phone columns can be queried through the column_values field on items queries using an inline fragment on PhoneValue.

query {
  items(ids: [1234567890, 9876543210]) {
    column_values {
      ... on PhoneValue {
        country_short_name
        phone
      }
    }
  }
}

Fields

You can use the following fields to specify what information your PhoneValue implementation will return.

Filter

You can filter items by phone values using the items_page object. The phone column supports the following operators:

Example

The following example returns all items with a phone column value in the United States.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "phone"
            compare_value: ["US"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Mutations

Update

You can update a phone column using change_simple_column_value or change_multiple_column_values. You can send values as simple strings or JSON objects, depending on the mutation you choose.

change_simple_column_value

Send your values in the following format in value:

"+<phone number> <ISO-2 country code>"

The country code must be capitalized and separated from the number by a space.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "phone"
    value: "+19175998722 US"
  ) {
    id
  }
}

change_multiple_column_values

Send the phone and countryShortName keys as a JSON object in column_values, using an uppercase ISO-2 country code.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"phone\": {\"phone\": \"+12025550169\", \"countryShortName\": \"US\"}}"
  ) {
    id
  }
}

Phone Number Validation

Phone numbers must follow the valid national formatting rules for the specified country code.

The phone column uses:

• ISO 3166 for country codes
• The Google libphonenumber library for number validation

If you encounter validation errors, you can verify your number using the online tool.

Examples

Clear

You can clear a date column using change_simple_column_value or change_multiple_column_values.

change_simple_column_value

Pass an empty string in value.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "phone"
    value: ""
  ) {
    id
  }
}

change_multiple_column_values

Pass null or an empty string in column_values

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"phone\": null}"
  ) {
    id
  }
}