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.
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:
- Access the Connect API Keys Page Go to Connect > API Keys.
- 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.
- 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).
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.
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.
- Individual Number Level On the 'Details' page for each number, click Edit Display and Settings.
Step 5: Enable or Disable Secure Branding
All Numbers
To apply Secure Branding to all your numbers:
- Click Enable for All Numbers to activate Secure Branding for every registered number.
- Click Disable for All Numbers to turn off Secure Branding across all numbers.
Individual Numbers
To manage Secure Branding on specific numbers:
- Go to Update Secure Branding for Individual Numbers.
- Select the numbers you want to edit.
- 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
Parameter | Type | Description | Example |
---|---|---|---|
customerId | String | Unique identifier for the customer | "87d8e330-2878-4742-a86f-dbbb3bf522ac" |
originatingPhone | String | Phone 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" | String | Phone number receiving the request, in E.164 format. | "15551234567" |
timeToLiveSeconds | Integer | Time in seconds for which the request is valid. Set 0 for no expiration. | 300 |
callReason | String | A 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:
- Go to Connect > Call Performance > Secure Branding Tab.
- 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).