Phone number

Phone number attributes represent telephone numbers. They are represented in E164 format and always prefixed with a country code.

The person object comes with a phone number attribute (phone_numbers), which is is a multi-select attribute, but users can also create their own phone number attributes on other objects or lists as well.

There are three properties on a phone number: original_phone_number (as inputted by the user), country_code (an ISO 3166-1 alpha-2 country code) and normalized_phone_number (as set by Attio). All properties are represented as strings.

Reading values

{
  "active_from": "2023-04-03T15:21:06.447000000Z",
  "active_until": null,
  "created_by_actor": {...},
  "attribute_type": "phone-number",
  "original_phone_number": "+15558675309",
  "normalized_phone_number": "+15558675309",
  "country_code": "US"
}

Writing values

You may either write phone number values as strings or objects. For both formats, you must provide sufficient information to identify the country code of the number.

For string values, the phone number must be prefixed with the area code, starting with "+".

Object values must include both a original_phone_number and country_code property. You may pass null to country_code if an area code prefix is provided as part of original_phone_number.

All values are validated against the E164 format.

Since the phone_numbers attribute is multi-select, you must always pass values as part of an array.

{
  "phone_numbers": ["+447777777777"]
}

{
  "phone_numbers": [
    {
      "original_phone_number": "+447777777777",
      "country_code": "GB"
    }
  ]
}

{
  "phone_numbers": [
    {
      "original_phone_number": "+44 7777777777",
      "country_code": null
    }
  ]
}

Filtering

Phone numbers can be filtered by equality or substrings ($eq,$contains,$starts_with,$ends_with). Note that the explicit property is called phone_number, internally Attio will use the normalized phone number for searching.

The country_code property can also be filtered by $eq and $not_empty.

{
  "filter": {
    "phone_numbers": "+15558675309"
  }
}

{
  "filter": {
    "phone_numbers": {
      "country_code": {
        "$eq": "US"
      }
    }
  }
}

{
  "filter": {
    "phone_numbers": {
      "phone_number": {
        "$contains": "67530"
      }
    }
  }
}