Skip to contentSkip to navigationSkip to topbar
On this page

Marketplace Add-on Listing Tutorial


This tutorial provides instructions for installing and using Marketplace Add-on listings such as Trestle Reverse Phone and Prove TCPA Compliance in the Twilio Lookup API. After reading this document, you will be able to install and use these Add-ons. For more detailed instructions on how to install and configure an Add-on listing, visit our usage guide.


Install an Add-on Listing

install-an-add-on-listing page anchor

Add-on Listings can be installed and enabled through the Twilio Console. Once installed, they enhance specific Twilio APIs, such as Twilio Voice and Programmable Messaging. Two popular features from Marketplace Add-ons are extracting information about a phone number's current owner and ensuring a number is compliant with Telephone Consumer Protection Act (TCPA) regulations.

To get information about a phone number's current owner, enable an Add-on called Trestle Reverse Phone. Inside the new Marketplace catalog, all available API Add-ons are listed. Select Trestle Reverse Phone from the catalog.

Add-ons Catalog — Trestle Reverse Phone.
Add-ons Trestle Reverse Phone — Overview.

Clicking on the Add-on provides additional information, including a description and access to the product's documentation. The two key pieces of information on this screen are:

  1. What APIs this can be enabled on — listed under Supported Products
  2. Whether or not the Add-on is Installed

Click Install. All installed Marketplace Add-ons can be viewed by clicking on Marketplace > Installed.

Trestle Reverse Phone Add-on - Configure.

Since the goal is to perform a Lookup on a phone number, check the Lookups box under the Configure tab.


Use the Trestle Reverse Phone Add-on Listing

use-the-trestle-reverse-phone-add-on-listing page anchor

The Trestle Reverse Phone Add-on is now enabled for Lookup. Use the Twilio Lookup API to get data about a target phone number. Replace my_trestle_addon with the value from the UNIQUE NAME field on the Configure tab in the following code example:

curl --location --request GET 'https://lookups.twilio.com/v1/PhoneNumbers/+14155551212?AddOns=my_trestle_addon' -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Example response:

1
{
2
"code": null,
3
"message": null,
4
"results": {
5
"trestle_caller_id": {
6
"code": null,
7
"message": null,
8
"request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
9
"result": {
10
"phone_number": "2069735100",
11
"is_valid": true,
12
"country_calling_code": "1",
13
"line_type": "NonFixedVOIP",
14
"carrier": "tw telecom",
15
"is_prepaid": false,
16
"is_commercial": true,
17
"belongs_to": [
18
{
19
"name": "Trestle Solutions Inc.",
20
"age_range": null,
21
"gender": null
22
}
23
],
24
"current_addresses": [
25
{
26
"street_line_1": "12819 SE 38TH ST # 263",
27
"street_line_2": "",
28
"city": "Bellevue",
29
"postal_code": "98006",
30
"zip4": "1326",
31
"state_code": "WA",
32
"country_code": "US",
33
"lat_long": {
34
"latitude": 47.608624,
35
"longitude": -122.334442,
36
"accuracy": "RoofTop"
37
},
38
"is_active": true,
39
"delivery_point": "MultiUnit"
40
}
41
],
42
"associated_people": [],
43
"alternate_phones": [
44
"8003361327"
45
],
46
"warnings": []
47
}
48
},
49
"status": "successful"
50
}
51
}

The JSON response provides basic information about the queried phone number. Depending on the type of phone number found, different subsets of information may be returned. These results are organized into a structured format. More information on all potential return values and keys can be found on the Documentation tab of the Listing's details page.


Use the Prove TCPA Compliance Add-on Listing

use-the-prove-tcpa-compliance-add-on-listing page anchor

Another Add-on, Prove TCPA Compliance, protects businesses from hefty fines levied under TCPA regulations for texting the wrong number. It can quickly verify if the number to which an SMS is about to be sent is active and still owned by the customer, with 100% reliability.

To use this Add-on, install it just like Trestle Reverse Phone. Go to the Add-on catalog(link takes you to an external page), locate and click on Prove TCPA Compliance, and click Install.

Add-ons Prove TCPA Compliance.

Since the goal is to leverage the Twilio Lookup API to find TCPA compliance information for a phone number, check the Lookups box under the Configure tab of the Prove TCPA Compliance Add-on. Afterwards, query for the TCPA compliance information on the target phone number using the following code:

curl --location --request GET 'https://lookups.twilio.com/v1/PhoneNumbers/+16505399600/?AddOns=prove_tcpa_compliance&AddOns.prove_tcpa_compliance.RightPartyContactedDate=20160101' -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Example response:

1
{
2
"Status": 0,
3
"Description": "Success",
4
"RequestId": "7f83-b0c4-90e0-90b3-11e10800200c9a66",
5
"Response": {
6
"VerifyNumberTransactionId": "144356671",
7
"PayfoneAlias": "C24C4C54DR10481C4E0U44ERMVUP9S1TUNXPLA2T753ETMCFOA086TYMCAQL00B4E0CLC4C24BHZPO4QWPN68EAV14ERTVPMMEP7OCXTRBQR17YERTMK749",
8
"MSISDNType": "Mobile",
9
"NumberMatch": "Y"
10
}
11
}

The results from the TCPA Compliance Lookup are organized into a structured format. The key NumberMatch indicates Y for a compliant number, N for a non-compliant number, and I for an indeterminate number. The response also includes keys related to the identification of the device claiming ownership of the number. For demographic and carrier information, use the Trestle Reverse Phone Add-on.

For more information on using Marketplace Add-ons, refer to the How to use Add-on Listings Guide.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.