Marketo Data Enrichment with Telnyx Number Lookup

This post will help you improve your audience segmentation, form conversions, and sales prioritization by using the Telnyx number lookup API through webhooks for Marketo data enrichment.

Telnyx is a next-generation telecommunications provider that makes it very easy for developers to programmatically embed voice, sms, and wireless solutions into their products. They are the up and coming superstar in the CPaas (communications platform as a service) space where Twilio is currently the dominant incumbent (think David versus Goliath).

Full disclosure I am the marketing operations lead at Telnyx so I may be just a smidge biased in my comparison 😛

Telnyx’s communication APIs open up a number of marketing possibilities when combined with the power of marketing automation platforms such as Marketo, Hubspot, and Active Campaign. All three of these platforms have webhook features, which allow you to make GET or POST requests to APIs (see Marketo API Quick-Start Guide for an introduction to APIs and requests).

This means we can use webhooks to unlock the power of Telnyx for sending SMS notifications (future blog post to come!) or enriching your lead database using number lookup, which is what this post will focus on.

Telnyx offers both a public number lookup API and a private number lookup API to allow you to get information on a phone number e.g.

• Country Code (Public & Private)
• State (Private)
• City (Private)
• Number Type (Public & Private)

Unlike the Twilio number lookup API, both of these Telnyx lookup APIs are free to use. The private number lookup API provides more information e.g. state and city, than the public API.

In order to access the private API you will need to create a Telnyx portal account, which is free and will also give you $10 of credit if you sign-up with a business email.

N.B. Using the referral link above will get you an extra $20 in free credit by directing you to the sign-up page with the promo code TYRON-W4KX prepopulated.

Hopefully, you can already see the useful information that a number lookup can provide but to elaborate more here are some of the insights that can be used to improve your marketing or sales outreach.

Number Lookup Benefits & Insights

Number Verification, Lead Scoring, & Sales Prioritization

The successful return of information about a number can act as a number verification process and can be used to deprioritize leads who enter fake numbers e.g. 123-456-7891.

Additionally, the type of number (mobile, fixed line, voip) associated with a lead could allow the sales team to prioritize phoning leads with mobile numbers over leads with landline numbers because they might be more likely to get through calling a personal cell.

If this is the case, demographic scoring models can be updated to give more points to leads with verified mobile phone numbers.

Improved Segmentation

Having improved geographic information will allow you to better segment your database for marketing or sales outreach.

The information provided by the number lookup can be used to supplement any existing enrichment processes you have to populate these fields e.g. form fills, 3rd party enrichment tool, manual sales entry.

You can create formula fields in Salesforce or Marketo that use logic to populate your fields with number lookup fields if the default fields are empty.

State = IF(ISBLANK(defaultState),lookupState,defaultState)

Alternatively, you can create Marketo smart campaigns to populate fields with lookup information when they are empty.

Reducing Form Fields & Increasing Conversion

Now that you know you can use a number lookup to gain geographic and other information this might allow you to reduce the number of fields in your forms and thereby increase conversion.

Calling the API using Marketo Webhooks

N.B. You can use the free Postman API testing tool to test out both of these number lookup APIs before bring them into Marketo webhooks. If you want a walkthrough of how to get started making your first Postman GET and POST requests then check out the Testing the Marketo API using Postman section of the Marketo API Quick-Start Guide.

Telnyx Public Number Lookup API Webhook

Configuring the webhook for the public Telnyx number lookup API is as simple as pasting the URL below into the URL field and mapping the response parameters to their corresponding Marketo field API name.

https://api.telnyx.com/anonymous/v2/number_lookup/{{lead.Phone Number}}

Telnyx Private Number Lookup API Webhook

Setting up the webhook to call the private Telnyx number lookup API requires the authorization header for the request to be populated with your Telnyx API key.

To create an API key:

1. Login to your Telnyx account
   1. Or create a new account and get $20 free credit using the promo code TYRON-W4KX
2. Select “API Keys” from the left-hand navigation
3. Select “Create API Key”
4. Click “Create”
5. Copy the “API Key”

If you already have an API key then you can simply copy the key from the “API Keys” section of the portal.

Next follow these steps in Marketo to set up the Authorization header:

1. Click on “Webhook Actions”
2. Select “Set Custom Header”
3. Click “Add”
4. Put “Authorization” in the header column
5. Put the word “Bearer” followed by a space in the “Value” column
6. Paste your Telnyx API key in the “Value” column

Now all you have to do is paste the code below into the URL field of the webhook and map the response attributes to their corresponding Marketo fields.

https://api.telnyx.com/v2/number_lookup/{{lead.Phone Number}}?carrier&caller-name

Calling the Lookup Webhooks in a Smart Campaign

It is worth noting that webhooks can only be called in smart campaigns from trigger actions so if you want to backdate this lookup information on all the leads already existing in your database you will have to trigger something on all these leads.

For newly created leads, form fills, or changes in the phone number field you can use a smart campaign to call the number lookup webhook.

Data Normalization Requirements

Number Format

In order for the number lookup API to pull the correct information for your phone number it needs to be in international format i.e. +1574-326-9202.

If your numbers are not in this format then you will need to use a tool like Flowboost or Zapier with Marketo webhooks to format your numbers like this when leads are created or phone numbers change. If you want to convert the numbers already in your database to this international format then you can export your database to a CSV and then use Google sheets or a programming script e.g. Python with the Pandas library, to do the tidy up.

Mapping Country Codes to Countries

The output of the lookup country code is a 2 letter code so if you want to map this code to its corresponding country then you will have to use a tool like Flowboost or Zapier with Marketo webhooks.

Alternatively for backdating you can:

1. Export your leads to a CSV containing at a minimum email address and country code
2. Use a vlookup formula in Google sheets to map country codes to their names
   1. Here is a Google sheet mapping country codes to country names thanks to Sanford Whiteman
3. Export a CSV of email addresses with correctly mapped country names
4. Import this CSV into a list in Marketo
   1. Beware that this will overwrite the country field if it is already populated so make sure that the list you export in Step 1. only contains leads with empty country fields or you know for sure that you want to overwrite their country field

What’s Next with the Telnyx API?

Now that you can enrich your lead database using the number lookup API and reap all the benefits you might be wondering what other ways Telnyx can serve you as a marketer.

Wonder no more! Explore how you can use the Telnyx SMS API in Marketo to send notifications e.g. webinar reminders, and how to handle response messages using Zapier to unsubscribe people or send follow-up SMS.

1. Marketo SMS Marketing with Telnyx
2. Marketo Text Messaging with the Telnyx SMS API
3. Marketo 2 Way SMS using Telnyx and Zapier
4. Marketo SMS Integration Example: Webinar Reminders