Marketo Data Enrichment with Telnyx Number Lookup

This tutorial 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’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).

Today, we’ll be focusing on using webhooks to enrich your lead database using Telnyx’s number lookup.

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.

Hopefully, you can already see the useful information that a number lookup can provide but to elaborate more, we’ll dive into 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 helps 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, like form fills, 3rd party enrichment tools, or 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

Number lookup can be leveraged to gain geographic and other information from leads. This is important because it may allow you to reduce the number of fields in your forms and thereby increase conversion.

Calling the API using Marketo Webhooks

Note: You can use the free Postman API testing tool to test out both of these number lookup APIs before bringing 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 on the Workflow Pro blog.

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 or create a new account using a business email
2. Select “API Keys” from the left-hand navigation
3. Select “Create API Key”
4. Click “Create”
5. Copy the “API Key”
6. If you already have an API key then you can simply copy the key from the “API Keys” section of the portal.

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 you can paste the code below into the URL field of the webhook and map the response attributes to their corresponding Marketo fields.

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 without any separators between the numbers i.e. +15743269203.

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 when 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 job.

Mapping Country Codes to Countries

The output of the lookup country code is a 2 letter code -- 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
   • 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
   • 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 are certain 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! Make sure you check out our article on how you can use the Telnyx SMS API and Zapier to forward SMS to Slack, email, or another number.

Enjoyed the tutorial? Check out the full version on The Workflow Pro Blog!