Phone ID - Identity attributes: Active Call Status

📘

NOTE:

To add this feature to your account, contact a Telesign expert. This feature is currently available for customers with end users in select countries.

Use this identity attribute to check if the end user is actively engaged in an ongoing call. This helps prevent fraud by using ongoing call activity and type to determine the presence of Authorized Push Payment fraud.

Active Call Status allows you to take extra steps when the end user initiates a transaction. If the end user is actively engaged in a conversation with a potential scammer, you can decide whether you want to allow the transaction.

Based on the phone number provided in the API request, Active Call Status provides a true/false response (indicating whether the user is participating in a call). It provides the information on whether the end user initiated or received the call and its duration.

Examples

Request body

{
  "addons": {
    "active_call_status": {}
  }
}

Response 1: Active call

When a call is active, the is_call_active parameter returns True. The call_direction parameter returns either called or calling, depending on who initiated the call. The call_duration parameter shows the length of a call in seconds.

{
    "active_call_status": {
        "is_call_active": True,
        "call_duration": 120,
        "call_direction": "called",
        "status": {
            "code": 2800,
            "description": "Request successfully completed."
        }
    }
}

Response 2: Inactive call

When a call is not active, is_call_active returns False.

{
    "active_call_status": {
        "is_call_active": False,
        "call_duration": None,
        "call_direction": None,
        "status": {
            "code": 2800,
            "description": "Request successfully completed."
        }
    }
}

Response error examples

Active Call Status returns the applicable error code and a description of the error for status.code when a request isn't successfully completed. The examples below are a few that you might see. See status codes for a complete list of possible status codes. If error code 2806 is returned, please contact Customer Support Team to enable Active Call Status.

Code 2802 is returned when there is an unexpected error. 2810 is included in the response when a provider returns an unrecognized response.

Response 3: Error - request processing timeout occurred

Code 2811 is returned when the timeout is reached.

{
    "active_call_status": {
        "status": {
            "code": 2811,
            "description": "Request processing timeout.",
        }
    }
}

Response 4: Error - no active_call_status information is found

Code 2805 is returned when the provider returns null or empty values for the required parameters.

{
    "active_call_status": {
        "status": {
            "code": 2805,
            "description": "No active_call_status add-on information for phone number."
        }
    }
}

Response 5: Error - phone type is not applicable

Code 2804 is returned when the phone number is invalid, restricted, toll-free, or a pay phone number.

{
    "active_call_status": {
        "status": {
            "code": 2804,
            "description": "Phone number not applicable in active_call_status add-on."
        }
    }
}

Schema

Active Call Status request parameters

Active Call Status response parameters

Status codes