How can we help?

Using Identity Phone Validation API for conditional-based routing in Studio


Consider a scenario where Talkdesk admins want to detect and route potential fraudulent calls within Talkdesk Studio, or get insights regarding a designated phone number, or even a series of phone numbers. With Phone Validation API, it is possible to obtain insights about specific phone number(s), which can be used to do routing decisions in Studio.


Obtaining an OAuth client to call the API


In order to get access to any Talkdesk API, you first need to obtain an OAuth client using the Builder App present on your workspace.

 Please follow the instructions provided by the Talkdesk Developers Documentation page on  Creating a new OAuth client.

Bellow, you can find a screenshot with the settings for the OAuth client needed to access the Identity Phone Validation API.

Note: in “Grant Type” only the “Client credentials” and “Refresh token” checkboxes are selected. Also note that you will need to select the “identity-phone-validation:read” scope.




Configuring an Integration

In order to be able to use the API in the Studio flow, it is required to configure an integration. Please follow these steps to take so:


1. After logging in to your Talkdesk account, click on Admin[1], go to the Integrations[2]and select Add integration[3].



2. Select the “Custom Integration” option [4] and click Add integration [5].

3. Fill in the integration details:


  • Basic information [6] as:
    •  “Name”: pasteIdentity Phone Validation”.
    • “Description: paste “Identity Phone Validation Integration”.


  • Copy and paste on the Base path [7] field: api.talkdeskapp.<region>/identity/phonevalidations.
  • Select the Authentication type [8].
  • Insert the OAuth “Client ID” [9].
  • Place the OAuth “Client Secret” [10].
  • Replace <your_org> (including the <>) with your account name [11].
  • Choose the “OpenID Auth Scheme” [12].

Note: You can check your account name in your browser URL:
Also, adjust the URL domains to your regional cloud domain (com, eu, ca, etc.) on BOTH the Base Path URL and the Access Token URL. Make sure that both "Base path" and "Access Token URL" are set to "https://".


4. Click Save in the top right corner of the page.



5. Go to the Actions section [13] and click on Add action [14].



6. Fill in the “Basic information” [15] for the action with:

  • Name: “Get Phone Validation Data”.
  • Description: “Gets Phone Validation Data for a given phone number”.


  1. Fill in the URL details with the values on the following screenshot:
  • “Relative path” [16]: {{phone_number}}.
  • “Display name” [17]: phone_number.


  1. In the “Inputs and Outputs” section, fill in the “Output Schema” [18] with the following values: 

  "$schema": "",

  "type": "object",

  "title": "HTTP connector",

  "required": [],

  "properties": {

    "_embedded": {

      "title": "id",

      "type": "object",

      "properties": {

        "id": {

          "type": "string",

          "title": "id"


        "status": {

          "type": "string",

          "title": "status"


        "valid": {

          "type": "boolean",

          "title": "valid"


        "active": {

          "type": "string",

          "title": "active"


        "fraud_score": {

          "type": "integer",

          "title": "fraud_score"


        "recent_abuse": {

          "type": "string",

          "title": "recent_abuse"


        "voip": {

          "type": "string",

          "title": "voip"


        "prepaid": {

          "type": "string",

          "title": "prepaid"


        "risky": {

          "type": "string",

          "title": "risky"


        "carrier": {

          "type": "string",

          "title": "carrier"


        "line_type": {

          "type": "string",

          "title": "line_type"


        "country": {

          "type": "string",

          "title": "country"


        "do_not_call": {

          "type": "string",

          "title": "do_not_call"


        "success": {

          "type": "boolean",

          "title": "success"





  1. On the top right of the page, click Save as Draft.


10. Go back to the Actions [19] tab and click on the name of the newly created action [20].



  1. On the top right of the Action page, tick Test Action [21].
  2. Fill in the value field with a phone number to test the action [22] and select Execute [23]. You should see the API output without any errors.
  3. You can now publish the action by clicking the Publish button in the top right corner of the page.

Using the Integration in Studio

The Execute Action component in Studio allows you to use an integration on a studio flow.

To know more, please consult the component documentation here.

To set up the component to use the Identity Phone Validation Integration, please follow these steps: 


  1. Add a new “Execute Action” [1] component.
  2. Select the connection and action created in the previous step [2].
  3. When you’re done, click Add step.


  1. Select the phone number [3] to validate the input.

Note: In this case, we are using the source_phone variable that can be exposed in the Incoming call initial step component.


You can now map any of the outputs to studio variables in order to present them in the context or do routing decisions based on those values.

The available outputs and respective explanations can be found here.

In order to make routing decisions based on the Identity Phone Validation outputs from the “Execute Action” component, a “Conditional Statement” component can be used. For more details, please check the component documentation.



All Articles ""
Please sign in to submit a request.