Skip to main content

Secure Your Branded Call from Spoofers

Follow this guide to protect your branded phone numbers from spoofing by setting up Hiya's Connect API and Secure Branding features. This process ensures that your registered numbers are pre-authenticated, protecting both your brand and your customers.

Secure Branding Diagram

Step 1: Check for Secure Branding and API Controls​

If Secure Branding and Connect API are not yet activated, you won't see these controls or related analytics in your account. Contact your Account Representative to enable them.

Step 2: Generate Your API Keys​

To set up your account:

  1. Access the Connect API Keys Page Go to Connect > API Keys.
  2. Generate a Key
    • Click Generate API key.
    • Choose a key type: one for production and one for testing.
    • Enter a name for your key and select Generate. Generate an API Key
  3. Manage Keys
    • Once generated, your API key and details will appear in the key table.
    • To reveal the API “secret,” click the eye icon.
    • To delete a key, select the overflow menu icon (three dots). Manage Keys

Step 3: How Secure Branding Works​

With Secure Branding, Hiya pre-authenticates outbound calls to prevent spoofing. Unauthorized calls will be stripped of branding to safeguard your brand integrity. This feature works only on calls terminating within the Hiya Network.

How Secure Branding Works

Step 4: Manage Secure Branding Settings​

You can customize Secure Branding settings at different levels:

  • Bulk or Global Settings Under the Secure Branding tab in Connect > Phone Numbers, manage settings for multiple numbers at once. Bulk Number Management
  • Individual Number Level On the 'Details' page for each number, click Edit Display and Settings. Single Number Management

Step 5: Enable or Disable Secure Branding​

All Numbers​

To apply Secure Branding to all your numbers:

  1. Click Enable for All Numbers to activate Secure Branding for every registered number.
  2. Click Disable for All Numbers to turn off Secure Branding across all numbers.

Individual Numbers​

To manage Secure Branding on specific numbers:

  1. Go to Update Secure Branding for Individual Numbers.
  2. Select the numbers you want to edit.
  3. Choose Enable selected or Disable selected as needed.

Step 6: Register Outbound Calls​

When initiating an outbound call, use the Register Outbound Call API to notify Hiya for pre-authentication. This step confirms the legitimacy of the call, allowing real-time branding.

Refer to the Register outbound call API.

Register outbound call​

This API is invoked to notify Hiya that the enterprise is about to make an outgoing phone call. It will pre-authenticate the phone call and optionally show additional real-time information to the end user, if provided.

  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  "originatingPhone": [string],
  "terminatingPhone": [string],
  "timeToLiveSeconds": 0,
  "callReason": [string]

Parameters​

ParameterTypeDescriptionExample
customerIdStringUnique identifier for the customer"87d8e330-2878-4742-a86f-dbbb3bf522ac"
originatingPhoneStringPhone number of the calling party (must be registered to this Hiya Connect account). The phone number is in E.164 format. If no userPhone is provided, then all phone numbers registered to the customer id will be authenticated to call the terminatingPhone"18001234567"
terminatingPhone"StringPhone number receiving the request, in E.164 format."15551234567"
timeToLiveSecondsIntegerTime in seconds for which the request is valid. Set 0 for no expiration.300
callReasonStringA piece of text information about the purpose of the call. This might include a reason for this call (e.g. "Confirm delivery" or "Customer satisfaction survey"). If set to an empty string (""), this will disable the static call reason set in the Connect console. If it's missing or null, the call will use the static call reason."Customer inquiry"

Example​

  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  "originatingPhone": "18001234567",
  "terminatingPhone": "15551234567",
  "timeToLiveSeconds": 300,
  "callReason": "Customer inquiry"

Step 7: Access Spoof Protection Analytics​

View detailed analytics on spoof protection:

  1. Go to Connect > Call Performance > Secure Branding Tab.
  2. Metrics Available:
    • Secure Branding Usage: Number of phone numbers with Secure Branding enabled.
    • Unauthorized Calls: Percentage of outbound calls blocked due to spoofing.
    • Spoofed Call Report: View spoofed numbers and their spoof rates over selectable time periods (e.g., last 7, 30, or 90 days).

Call Performance