The phone column stores a phone number with a relevant country code. Our API supports this column, so you can read and update the phone column via the API.

Reading the phone column

You can return the data in a phone column in two different formats. The text field will return the data as a simple string, and the value field will return the data as a JSON string.

  "text": "1123456789",
  "value": "{\"phone\":\"+12025550169\",\"changed_at\":\"2022-07-21T12:00:00.000Z\",\"countryShortName\":\"US\"}"

Updating the phone column

You can update a phone column with both a simple string and a JSON string.

Simple strings

To update a phone column value, send "+" followed by the phone number. You also need to send the ISO-2 country code (a two-letter code) as a string. Make sure to separate the phone number and country short code with a space.

You can see the list of available countries here.

For example: "+19175998722 US"


To update a phone column, send "+" followed by the phone number in the phone field, and the ISO-2 country code (a two-letter code) in the countryShortName field.


You will receive an error if you do not use capital letters for the 2-letter country code.

You can see the list of available countries here.

For example: "{\"phone\":\"+12025550169\",\"countryShortName\":\"US\"}"

mutation {
  change_multiple_column_values(item_id:9876543210, board_id:1234567890, column_values: "{\"phone\" : {\"phone\" : \"+12025550169\", \"countryShortName\" : \"US\"}}") {
fetch ("", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY'
  body: JSON.stringify({
    query : "mutation ($myBoardId:Int!, $myItemId:Int!, $myColumnValues:JSON!) { change_multiple_column_values(item_id:$myItemId, board_id:$myBoardId, column_values: $myColumnValues) { id }}",
    variables : JSON.stringify({
      myBoardId: YOUR_BOARD_ID,
      myItemId: YOUR_ITEM_ID,
      myColumnValues: "{\"phone\" : {\"phone\" : \"+12025550169\", \"countryShortName\" : \"US\"}}"

You can find the Postman request to change the phone column here.

Clearing the phone column

You can clear the phone column using a change_multiple_column_values mutation.

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

Phone number validation

The phone column is essential for many users who use it widely across many boards, integrations, and automations. To ensure that the columns function as expected, you must provide correct and valid phone numbers.

Our system validates its validity and format each time a user submits a new column value. It must adhere to the requirements to work as expected. For example, let's say you use an integration with a call system. If the phone column value isn't input correctly, you can't call your customer.

Our system accepts a phone number and country code in ISO 3166 format. It also uses the Google Phone Library to validate the accuracy of the number with the country code.

Check out the following examples of valid phone numbers:

United States (US)


Great Britain (GB)


Australia (AU)


If you are struggling with invalid column values, you can verify the accuracy of the phone number using an online tool.


Have questions?

Join our developer community! You can share your questions and learn from fellow users and product experts.

Don’t forget to search before opening a new topic!