In this article we are going to be creating a new workflow that we will specifically use to check if our contacts phone numbers are "wireless" or if they are a landline.

Once we have everything created we will be able to simply "enroll" our contacts into this new workflow at any time to look up their phone number. Within this article we will be breaking down the process into multiple sections to make it easier to follow.

You will want to have some basic understanding of how to upload or add contacts into your system as we won't cover the specific details in this article. See the "Contacts" article for more details on uploading or adding contacts to your system.

Creating a number Set

First thing we will want to do is create a number set. If you already have an existing number set then you can skip this section and move on to the next section.

Anytime you create a workflow, it requires a "number set". Number sets are simply groups of numbers that will be used to send out the SMS or make phone calls from your workflow if your workflow is setup to perform those actions.

In our case, we technically will not be sending out any SMS or making any phone calls that would require phone numbers, but we still are required to have a number set. We won't be adding any numbers to this number set as that is not going to be needed for our setup.

1. Within your API portal, click on "Numbers" section

2. Click on "Number Sets"

3. Click on "Create number Set"

4. Within the Number set name section enter the words "Carrier Lookup Workflow"

5. Click the "Create" button

DONE!

Creating a Connection to Ytel API

Connections are used to authenticate our information with the API that we will be using. We will be using our v4 API which uses a Bearer token as our authentication method. This means we will first need to create a new Bearer token.

Creating a Bearer Token

The Bearer Token we will be creating is no different than a password. Meaning keep this unique code safe as anyone who has your bearer token will be able to use it for any API calls on your account.

1. Within your API portal, click on the Settings option

2. Click on the API Tokens section

3. Ensure you are in the Ytel API v4 tab

4. Click on the Create token button

   

5. Give your Token a Name and either set it to never expire or select a future date and time for the token to expire (if you select a future expiration date, then you will need to create a new token once that date and time hits).

6. Click on Confirm

    

   

7. You will receive a Token successfully generated! prompt

8. Click on the copy key to clipboard button to copy your token

    

Important: Once your token has been created and you close the window, you will NOT be able to see this token again. If you will need to have a copy of this token for future use it will be important to save this information in a secure location on your computer such as a password manager tool. Again treat this like any other password!

Creating a Connection

Now that we have our Bearer token created, lets go ahead and create a new connection. We will first want to navigate to the "Connections" section within the API portal.

1. Log into your API portal and click on Workflows

2. Select Webhooks from the menu

3. Click into the Connections tab

4. Click on the Create Connection button

    

   

5. Give the connection a Name (we will be calling ours Ytel API v4)

6. In the Description, we can include more details about this connection type. This simply will give us more details on what this connection does. In our case we will simply put the same information into Description as we did for the Name field.

7. Click on Add authorization header

8. Enter the text "Authorization" into the Key field

9. Enter the text "Bearer" followed by a space and then paste in your bearer token you copied earlier into the Value field. (i.e. Bearer e12dkajadfkasdfj...)

10. Under the Headers, section click on Add header

11. Enter in the text "Content-Type" into the Key field

12. Enter the text "application/json" into the Value field

13. Press the Save button

Note: Do not include quotes in the text boxes.

We have now successfully created a Connection to our v4 API. Keep in mind that we can now use this connection not only on the carrier look-up Webhook we are about to create, but any other Ytel Webhook we might create in the future as long as we are using our v4 API calls.

DONE!

Creating a Webhook for our Carrier Lookup API

With the connection out of the way, let's go ahead and create a Webhook for our Carrier Lookup API. For more information on our Carrier Lookup API please refer to our API documentation.

1. Log into your API portal and click on Workflows

2. Select Webhooks from the menu

3. Press the Create webhook button

   

4. We will be entering "Ytel CarrierLookup" into the Name field

5. Select the "Ytel API v4" connection from the drop-down menu of the Connection setting

6. For Method, we will be using a "GET"

7. For the Request URL, we will be entering in the following URL "https://api-beta.ytel.com/api/v4/carrier/lookup/PHONENUMBER1/"

8. We can skip the Content-type, Event type, Headers, and Request Body as that information is not needed for our Carrier Lookup API.

    

   

9. Under the "Response processing" section, enter the text "$.status" into the Success path field.

10. Enter the text "true" into the Success value field.

11. Within the "Response variables" section we will be adding all the information we wish to retrieve from the response our Carrier Lookup API will return (Scroll down below the steps to see an example of the response and the data our carrier lookup API returns.).

12. Let's go ahead and add the "wireless" field and the "network" field to our contacts that will be running through this workflow.

13. Click on "Add variable".

14. Enter the text "wireless" within the Variable name field (this will be the variable name we will be using in our workflow that will house the information we need. We could put any word we want in this field. We could even use the word "pizza" if we really wanted to).

15. Enter the text "$.payload[0].wireless" within the Path field (here we are telling it that we are interested in the value the API returns that is associated with the "wireless" field).

16. Let's add the "network" field next.

17. Click on "Add variable".

18. Enter the text "network" within the Variable name field.

19. Enter the text "$.payload[0].network" into the Path field.

20. Press the "Save" button.

     

    

Example Response from our Carrier Lookup API

{
  "status": true,
  "count": 1,
  "page": 1,
  "payload": [
    {
      "apiVersion": "4",
      "carrierSid": "578c10-1a24-11eb-bed0-a9d03de",
      "phoneNumber": "+19998881112",
      "network": "Cellco Partnership dba Verizon Wireless - CA",
      "wireless": true,
      "zipCode": "92602",
      "city": "Irvine",
      "state": "CA",
      "status": true,
      "dateCreated": "2020-08-23T08:49:22.640Z",
      "date": 1604002895441
    }
  ]
}

DONE!

Creating our Carrier Lookup Workflow

Now that our webhook is completed, we can create our "Carrier Lookup" Workflow which we will use to run our contacts through in order to obtain the wireless and network data for the contact.

1. Log into your API portal and click on Workflows.

2. Click on the "Create workflow" button.

   

3. For the Title, we will be calling it "Ytel Carrier Lookup".

4. Select your "Number Set" from the Select number set drop-down menu

5. For the Timezone protection let's select "None"

6. Click on "Create"

    

   

7. Click the "+" symbol and select the "Webhook" node

   

8. Within the "Webhook" node select the Webhook we created earlier in the article.

9. Click the "+" symbol on the Webhook node and select the "Edit Contact" node.

10. We are going to be selecting Assign Value from Campaign from the drop-down menu.

11. Within the variable text box enter in the word "wireless" (this will be the field on the contact that will be associated with the data we want. We could use an existing attribute or we can put whatever name we would like here and the system will add the attribute to the contact automatically if it does not exist.).

12. Within the value text box enter in the word "wireless". Remember this is the variable name we set earlier on the webhook. If we had used the word "pizza" as I mentioned earlier, then we would enter the word "pizza" here. This essentially holds the variable data.

13. Go through steps 11 and 12 again, but change the word "wireless" to "network", so we can capture that data as well.

14. Click the "+" symbol and select the "Stop" node

DONE!

Running your Contacts through your Carrier Lookup Workflow

The hard part is now done and behind us.

1. Navigate to the "Contacts" section and select one or more of your contacts you wish to run through this API.

2. Click on the "Start workflow" button

3. Select your Carrier Lookup workflow from the drop down menu

4. Click on "Enroll"

DONE!

Final Remarks/Thoughts/Words of Wisdom's

Creating a Connection and a Webhook might seem like a lot of steps at first, but once you understand how to create webhooks it greatly opens up all the possibilities and things you can accomplish when connecting API's together.

A few important things to keep in mind..

• Once a contact or a group of contacts are "enrolled" into an active workflow, for all intensive purposes you cannot stop a workflow. It must runs it's course.

• Some of our API's (such as the Carrier Lookup API) has a cost associated with it on a per use basis. This means if you are paying 0.003 per carrier lookup then each time you run a contact through this workflow your will be charged for the look up.

• When creating a Bearer token, make sure to keep it safe and treat it like any other password. If the Bearer token becomes compromised you can always delete it, so it is no longer active.