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.

Column Type	Implementation Type	Supported Operations
`phone`	`PhoneValue`	Read: Yes Filter: Yes Update: Yes Clear: Yes

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.

Field	Description
column `Column!`	The column the value belongs to.
country_short_name `String`	The ISO-2 country code.
id `ID!`	The column's unique identifier.
phone `String`	The phone number stored in the column.
text `String`	The column's value as text. Returns `""` if the column has an empty value.
type `ColumnType!`	The column's type.
updated_at `Date`	The column's last updated date.
value `JSON`	The column's JSON-formatted raw value.

Filter

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

Operators	Compare Values
`any_of`	ISO-2 country code (e.g., "US")
`not_any_of`	ISO-2 country code
`is_empty`	`[]`
`is_not_empty`	`[]`
`contains_text`	Partial or full phone number text
`not_contains_text`	Partial or full phone number text

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

Country	Accepted Formats
United States (US)	`"{\"phone\":\"+12025550172\",\"countryShortName\":\"US\"}"` `"{\"phone\":\"12025550172\",\"countryShortName\":\"US\"}"` `"{\"phone\":\"2025550169\",\"countryShortName\":\"US\"}"`
Great Britain (GB)	`"{\"phone\":\"+447975777666\",\"countryShortName\":\"GB\"}"` `"{\"phone\":\"447975777666\",\"countryShortName\":\"GB\"}"` `"{\"phone\":\"+442079460990\",\"countryShortName\":\"GB\"}"` `"{\"phone\":\"07975777666\",\"countryShortName\":\"GB\"}"`
Australia (AU)	`"{\"phone\":\"+61488870510\",\"countryShortName\":\"AU\"}"` `"{\"phone\":\"61488870510\",\"countryShortName\":\"AU\"}"` `"{\"phone\":\"0488870510\",\"countryShortName\":\"AU\"}"` `"{\"phone\":\"0255504321\",\"countryShortName\":\"AU\"}"`

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
  }
}