Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Transform your phone number formats to be compatible with Flex (Public Beta)


(warning)

Public Beta

Unified Profiles in Flex is currently available as a limited Public Beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by a Twilio SLA.

(warning)

Not a HIPAA Eligible Service or PCI Compliant

Unified Profiles in Flex is not a HIPAA Eligible Service or PCI compliant and should not be used in Flex or Segment workflows that are subject to HIPAA or PCI.


Overview

overview page anchor

For Unified Profiles to look up customer profiles correctly, phone numbers must be in E.164 format. However, in many cases, phone numbers stored in Segment use a different format. If phone numbers aren't in E.164, Unified Profiles cannot match phone numbers to customer profiles.

To enable Unified Profiles to work properly, you must transform phone numbers to E.164 format if they aren't already in that format.


Find out if your phone numbers are stored in E.164 format

find-out-if-your-phone-numbers-are-stored-in-e164-format page anchor
  1. In Segment, navigate to Unify > Profile explorer .
  2. Click a profile to view details.
  3. Review the phone number and manually compare the format to E.164.
    • If the phone number is in E.164, no action is needed.
    • If the phone number is in any other format, make a note of the trait name and the current format so you can determine what transformations are needed.
  4. If necessary, repeat steps 2-3 with additional profiles that might have different phone number traits that are stored in other formats.
  5. If you've found any phone numbers that are not in E.164, continue to the next section to learn how to transform them to E.164.

Transform your phone number format

transform-your-phone-number-format page anchor

Step 1: Gather information

step-1-gather-information page anchor
  1. Run the following curl command to obtain the SID. Be sure to update the command with your account SID and auth token.

    This SID will become the value for the secondary identifier, which we will refer to as PROFILE_CONNECTOR_INSTANCE_SID in the commands later in this procedure. This identifier was created during Unified Profiles setup.


_10
curl 'https://preview.twilio.com/ProfileConnector/ConnectorInstances' \
_10
--header 'Content-Type: application/x-www-form-urlencoded' \
_10
-u {ACCOUNT_SID}:{AUTH_TOKEN}

  1. Review the response and make a note of the sid value. You will enter this in the next step as the PROFILE_CONNECTOR_INSTANCE_SID .

_19
{
_19
"connector_instances": [
_19
{
_19
"sid": "PD59405a223e87ff8d70b530002c91ea06",
_19
"friendly_name": "SetupTestTemplate",
_19
"unique_name": "SetupTestTemplate",
_19
"type": "SEGMENT",
_19
"date_created": "2024-02-01T18:47:43.535494657Z",
_19
"date_updated": "2024-02-01T18:47:43.535494657Z",
_19
"version": "1"
_19
}
_19
],
_19
"meta": {
_19
"direct_token": true,
_19
"page_size": 2,
_19
"previous_token": null,
_19
"next_token": null
_19
}
_19
}

  1. Run the following curl command to retrieve identifiers for your account. Be sure to enter your PROFILE_CONNECTOR_INSTANCE_SID from the previous step as well as your account SID and auth token.

_10
curl 'https://preview.twilio.com/ProfileConnector/Configurations?Context=ProfileConnectorIdentifierConfiguration&SecondaryIdentifier={PROFILE_CONNECTOR_INSTANCE_SID}' \
_10
--header 'Content-Type: application/x-www-form-urlencoded' \
_10
-u {ACCOUNT_SID}:{AUTH_TOKEN}

  1. Review the response and make a note of the version and data values that are returned. You will use these values to transform your phone numbers to E.164.

_14
{
_14
"sid": "PF94d90a5c6f7e974e43ba320b6f79acb7",
_14
"context": "ProfileConnectorIdentifierConfiguration",
_14
"version": "1",
_14
"data": {
_14
"type": "IdentifierMapping",
_14
"identifier": "phone",
_14
"friendly_name": "Phone Number",
_14
"priority": 6,
_14
"transformations": null
_14
},
_14
"date_created": "2024-02-09T01:27:57.041694919Z",
_14
"date_updated": "2024-02-09T01:27:57.041694919Z"
_14
}

Step 2: Transform phone numbers to E.164 format

step-2-transform-phone-numbers-to-e164-format page anchor

In the last step of Step 1: Gather information, you can see that there is a transformations section. To create a transformation, you must enter a regular expression that is grouped to move variables around by completing the following steps:

  1. Create an object with the properties match_regex and formats. We will refer to this as a "transformation object." If you have multiple formats in your Segment data, you can include multiple transformation objects in the transformations array.

    Your transformation object must include the following properties:

    • match_regex is a string with the regular expression that will be used to separate the phone number into sections.
    • formats is an array of the possible formats, with $0 as the original format. Following is an example:

_10
{
_10
"match_regex": "^\\+1(\\d{3})(\\d{3})(\\d{4})$",
_10
"formats": [
_10
"$1 $2 $3",
_10
"$1-$2-$3",
_10
"$0"
_10
]
_10
}

For more examples, see Transformation array value examples below.

  1. Run the following curl command to apply the transformation objects to the identifier that you found in Step 1: Gather information . Be sure to replace all of the variables with the information you gathered and the transformation objects that you created.

_14
curl 'https://preview.twilio.com/ProfileConnector/Configurations/{PROFILE_CONNECTOR_IDENTIFIER_CONFIGURATION_SID}' \
_14
--header 'Content-Type: application/x-www-form-urlencoded' \
_14
--header 'If-Match: {CURRENT_VERSION}' \
_14
-u {ACCOUNT_SID}:{AUTH_TOKEN} \
_14
--data-urlencode 'RequireUnique=False' \
_14
--data-urlencode 'SecondaryIdentifier={PROFILE_CONNECTOR_INSTANCE_SID}' \
_14
--data-urlencode 'Context=ProfileConnectorIdentifierConfiguration \
_14
--data-urlencode 'Data={
_14
"type": "IdentifierMapping",
_14
"identifier" : "{IDENTIFIER_FROM_SEGMENT}",
_14
"friendly_name" : "{NAME_TO_SHOW_IN_UI}",
_14
"priority": {PRIORITY_FOR_SORTING_IN_UI},
_14
"transformations" : [{TRANSFORMATIONS_TO_APPLY}]
_14
}'

This example includes two transformation objects:


_27
curl --location 'https://preview.twilio.com/ProfileConnector/Configurations/PF94d90a5c6f7e974e43ba320b6f79acb7' \
_27
-u {ACCOUNT_SID}:{AUTH_TOKEN} \
_27
--header 'Content-Type: application/x-www-form-urlencoded' \
_27
--header 'If-Match: 2' \
_27
--data-urlencode 'SecondaryIdentifier=PD59405a223e87ff8d70b530002c91ea06 \
_27
--data-urlencode 'Context=ProfileConnectorIdentifierConfiguration' \
_27
--data-urlencode 'Data={
_27
"priority": 6,
_27
"friendly_name": "Phone Number",
_27
"identifier": "phone",
_27
"type": "IdentifierMapping",
_27
"transformations": [
_27
{
_27
"match_regex": "^\\+1(\\d{3})(\\d{3})(\\d{4})$",
_27
"formats": [
_27
"$1 $2 $3",
_27
"$1-$2-$3",
_27
"$0"
_27
]
_27
},
_27
{
_27
"match_regex": "^\\+370(\\d{3})(\\d{5})$",
_27
"formats": ["8.$1.$2"]
_27
}
_27
]
_27
}' \
_27
--data-urlencode 'RequireUnique=True'

Transformation array value examples

transformation-array-value-examples page anchor

In Step 2: Transform phone numbers to E.164 format above, you must determine what values to enter based on the kind of data you have and how your phone numbers are formatted. While we can't tell you exactly what to enter, here are a few examples to help guide you:

United States phone numbers
united-states-phone-numbers page anchor

In E164 format, a US phone number looks like this: +12121231234

US phone numbers are commonly stored in formats like these:

  • 456-7890
  • 212-456-7890
  • +1-212-456-7890
  • 1-212-456-7890

For this scenario, you would use the following match_regex and formats array:


_10
{
_10
"match_regex": "^\\+1(\\d{3})(\\d{3})(\\d{4})$",
_10
"formats": [
_10
"$2-$3",
_10
"$1-$2-$3",
_10
"+1-$1-$2-$3",
_10
"1-$1-$2-$3",
_10
"$0"
_10
]
_10
}

United Kingdom phone numbers
united-kingdom-phone-numbers page anchor

In E164 format, a UK phone number looks like this: +442012341234

UK phone numbers are commonly stored in formats like these:

  • 020 1234 1234
  • 020-1234-1234

For this scenario, you would use the following match_regex and formats array:


_10
{
_10
"match_regex": "^\\+44(\\d{2})(\\d{4})(\\d{4})$",
_10
"formats": [
_10
"0$1 $2 $3",
_10
"0$1-$2-$3",
_10
"$0"
_10
]
_10
}

Lithuanian phone numbers
lithuanian-phone-numbers page anchor

In E164 format, a Lithuanian phone number looks like this: +37060112345

Lithuanian phone numbers are commonly stored in formats like these:

  • 370-601-12345
  • 8-601-12345
  • 8 601 12345

For this scenario, you would use the following match_regex and formats array:


_10
{
_10
"match_regex": "^\\+370(\\d{3})(\\d{5})$",
_10
"formats": [
_10
"370-$1-$2",
_10
"8-$1-$2",
_10
"8 $1 $2",
_10
"$0"
_10
]
_10
}

Calls or messages coming from WhatsApp are appended with whatsapp: (for example, whatsapp:+37060112345). If you need to look up a phone number in your Segment instance and you don't have the WhatsApp formatting appended to it, you'll need to apply a format to handle this.

For this scenario, you would use the following match_regex and formats array to remove the whatsapp: prefix from the matched string and output only the phone number with the + sign.


_10
{
_10
"match_regex": "^whatsapp:(\\+.+)$",
_10
"formats": [
_10
"$1"
_10
]
_10
}

The resulting match will produce +37060112345 from the example above.

  • If you copy and paste your regex and it doesn't work, make sure you are using straight quotes instead of curly quotes.
  • If you decide to run your regex through a regex tester, you may need to replace all of the double backslashes with single backslashes for testing purposes only. In your match_regex attribute, you must use double backslashes.

If you no longer need a transformation or if you want to modify it, you can remove it with the following command. This command uses the same variables that you used when creating the transformation, but leaves out the transformation section so that all transformations are removed from the identifier.


_13
curl 'https://preview.twilio.com/ProfileConnector/Configurations/{PROFILE_CONNECTOR_IDENTIFIER_CONFIGURATION_SID}' \
_13
--header 'Content-Type: application/x-www-form-urlencoded' \
_13
--header 'If-Match: {CURRENT_VERSION}' \
_13
-u {ACCOUNT_SID}:{AUTH_TOKEN} \
_13
--data-urlencode 'RequireUnique=False' \
_13
--data-urlencode 'SecondaryIdentifier={PROFILE_CONNECTOR_INSTANCE_SID}' \
_13
--data-urlencode 'Context=ProfileConnectorIdentifierConfiguration \
_13
--data-urlencode 'Data={
_13
"type": "IdentifierMapping",
_13
"identifier" : "{IDENTIFIER_FROM_SEGMENT}",
_13
"friendly_name" : "{NAME_TO_SHOW_IN_UI}",
_13
"priority": {PRIORITY_FOR_SORTING_IN_UI}
_13
}'

Following is an example with the transformation objects removed:


_13
curl --location 'https://preview.twilio.com/ProfileConnector/Configurations/PF94d90a5c6f7e974e43ba320b6f79acb7' \
_13
-u {ACCOUNT_SID}:{AUTH_TOKEN} \
_13
--header 'Content-Type: application/x-www-form-urlencoded' \
_13
--header 'If-Match: 2' \
_13
--data-urlencode 'SecondaryIdentifier=PD59405a223e87ff8d70b530002c91ea06 \
_13
--data-urlencode 'Context=ProfileConnectorIdentifierConfiguration' \
_13
--data-urlencode 'Data={
_13
"priority": 6,
_13
"friendly_name": "Phone Number",
_13
"identifier": "phone",
_13
"type": "IdentifierMapping"
_13
}' \
_13
--data-urlencode 'RequireUnique=True'


Rate this page: