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.

Prerequisites

Before you can successfully announce outbound calls, the following need to be in place:

• Secure Branding enabled for your account, via your Hiya Account Representative or the Connect Portal (Step 1).
• API keys generated for your integration, one for testing and one for production (Step 2).
• Secure Branding turned on for the specific numbers you'll be calling from
• (Optional)Call reasons preregistered and approved in the Connect console, if you plan to use dynamic callReason values on your announcements (Step 6).
• Your dialer or telephony platform updated to announce each outbound call via the Announce Outbound Call API before dialing, using a timeToLiveSeconds window that matches your actual latency (Step 6).

Step 1: Check for Secure Branding and API Controls

Secure Branding must be enabled for your account before you can use it. You can request access in either of two ways:

• Contact your Hiya Account Representative and ask them to enable Secure Branding for your account.

• Request access through the Connect Portal, if self-service enablement is available for your account. Once Secure Branding is enabled, two things become available:

• Options to enroll individual phone numbers into Secure Branding (used in Steps 4–5).

• A new API Keys page for managing your Connect API credentials (Step 2).

Step 2: Generate Your API Keys

Connect API requests are authenticated using Basic HTTP Authentication (an App ID and App Secret, base64-encoded into an Authorization header) — see Authentication for the exact header format.

To generate keys for 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.
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).

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:

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: Announce Your Outbound Calls

Once Secure Branding is enabled on a number, every call from that number needs to be announced to Hiya before it's placed, or it won't be pre-authenticated. Use the Announce Outbound Call API to notify Hiya that a specific call is about to happen — this confirms the legitimacy of the call and enables real-time branding.

Refer to the Announce outbound call API reference.

When to announce a call

Call the API as part of your call-setup step — after your system decides to place the call, but before it actually dials:

1. Your system decides to call +15551234567 from +18001234567.
2. You call the Announce Outbound Call API for that pair. (this step)
3. You receive a 200 response confirming the announcement.
4. You place the actual call.

Don't place the call before the announcement completes. If the real call reaches Hiya's network before, or without, a matching announcement, it's treated as unauthenticated and stripped of branding — the same treatment a spoofed call would get.

How long the announcement is valid

Each announcement includes timeToLiveSeconds: the window, starting when Hiya receives it, during which the real call must arrive to be matched. Keep this window tight and realistic for your actual dialing latency — a short-lived announcement that expires before you dial is a common cause of calls unexpectedly losing branding. If your dialer retries or delays a call, re-announce it rather than relying on the original window. Moreover, keeping this window open for too long increases the risk of a spoofed call escalping detection.

Confirming the announcement succeeded

A 200 response means Hiya received and processed the announcement — it does not by itself guarantee the call is pre-authenticated everywhere it might terminate. The response includes a regionalResponses array with one entry per Hiya region that evaluated the announcement; check the status for the region(s) relevant to the number you're calling.

If the announcement fails outright, see HTTP Error Status Codes for what each status means. A 429 usually means you're announcing faster than your account's rate limit allows — add backoff before retrying.

Request

{
  "originatingPhone": "+18001234567",
  "terminatingPhone": "+15551234567",
  "timeToLiveSeconds": 15,
  "callReason": "Customer inquiry"
}

Parameters

Parameter	Type	Description	Example
originatingPhone	String	The calling number, in E.164 format. Must already be registered and branded to this Hiya Connect account, with Secure Branding enabled.	"+18001234567"
terminatingPhone	String	The number being called, in E.164 format. Used to match this announcement to the real call when it reaches Hiya's network.	"+15551234567"
timeToLiveSeconds	Integer	How long, in seconds, this announcement stays valid after Hiya receives it. The real call must reach Hiya's network within this window to be authenticated.	300
callReason	String	The purpose of the call, shown to the end user alongside your branding. Must exactly match one of the call reason texts preregistered, vetted, and approved for this account in the Connect console.	"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).