With the Branded Call API, you can pre-authorize your outbound calls before they reach the network. Secure Branding is the feature that uses that pre-authorization: once it's enabled on a phone number, calls from that number are checked against your pre-authorization data, and any call that doesn't match is stripped of its branding before it reaches the recipient. The two are covered together here because Secure Branding depends on the API integration being in place — enabling one without the other changes what happens on a call, which is why the order you set them up in matters.
Jump to:
- Why don't I see the Secure Branding and API controls?
- API keys
- How Secure Branding works
- When Secure Branding may be required
- Before you enable Secure Branding
- Secure Branding controls
- Spoof protection analytics
Why don't I see the Secure Branding and API controls?
If the Branded Call API and Secure Branding are not yet enabled, you will not see the controls and analytics mentioned below. If you would like to enable these features, please contact your Account Representative.
API keys
To generate and manage your API keys, navigate to the API keys page under the Branded Call section.
To generate a key, click the "Generate API key" button. You can create a maximum of one key for use in a production environment and one for testing purposes. Select your key type, enter a key name, and generate your key.
A key will be automatically generated, and details will be displayed in the key table. Branded Call API keys include an API ID and an API "secret" that can be revealed by clicking the eye icon. To delete a key, click the overflow menu icon (three dots) to the right.
There is also a link to open and view the technical documentation of the Branded Call API.
Who sends the pre-authorization call. It's whichever system in your call path manages the technical connection to Hiya — that might be your own dialler or phone system, or it might be a partner acting on your behalf, such as a contact-center platform or communications provider. It doesn't have to be sent from the same system that places the call, and it doesn't involve your carrier at all: the pre-authorization travels to Hiya over the internet, separately from the call itself, and only needs to arrive before the call reaches the receiving network. If you connect to Hiya through a partner, confirm with them which of their systems is responsible for sending it.
How Secure Branding works
Secure Branding uses a short message — an announcement — sent to Hiya just before a call happens, separately from the call itself. Here's the sequence:
- Announce. Your system (or your partner's, on your behalf) tells Hiya which of your numbers is about to call which receiving number.
- Record. Hiya holds that as a temporary record for a short time.
- Place the call. The call goes out as normal, over your usual carrier — the announcement and the call travel completely separately and only need to arrive at the same place, at the receiving end, within that short window.
- Check. When the call reaches the receiving mobile network, that network asks Hiya whether it has a matching, unexpired record for that exact pair of numbers.
- Display. If there's a match, Hiya returns your approved branding and the call displays as normal. If there's no match — because nothing was announced, the numbers don't line up, or the record has already expired — the call reaches the recipient without your branding.
This is why Secure Branding depends on your announcement completing before the call, and why it's a fraud control rather than a display feature in its own right: a call that was never announced simply can't be matched, which is the point.
Why it doesn't work identically on every network. Even with the announcement working correctly, two carrier-side factors determine whether branding actually reaches the recipient:
- VoLTE. Branding information isn't carried over a 2G connection. On some operators, VoLTE (voice over LTE) also has to be switched on for the recipient's specific mobile contract by their carrier — having a VoLTE-capable phone isn't automatically the same thing. If the receiving device or connection drops to 2G, or VoLTE isn't provisioned on that line, the call will typically display the bare number with no branding, even though everything on your side worked.
- Caller-ID field alignment (PAI and FROM). Every call carries two technical caller-ID fields that are supposed to match. On some carriers, a trunk or routing provider further along the call path can make these two fields differ — this is something that happens on the network side, not something you configure. When it happens, branding can fail silently on that specific carrier even though your announcement and setup are correct. It doesn't happen on every network, so it's worth ruling out rather than assuming.
When Secure Branding may be required
Some carriers may require Secure Branding before branding will display at all for financial services and government callers. Requirements and availability can vary by carrier and market. Contact your Account Representative to confirm what applies to your calls.
If Secure Branding is required and available for your calls, setup generally involves these steps:
- Hiya enables Secure Branding on your account and issues your API credentials.
- Your technical team integrates the Secure Branding API into your dialler or call system.
- Once you confirm the integration is working correctly, Hiya can enable distribution on a supported network.
If Secure Branding is enabled before your integration is working, your calls can lose branding across networks. See the next section before enabling it.
Before you enable Secure Branding
Secure Branding and the Branded Call API pre-authorization are meant to be enabled together, and once you enable Secure Branding on a number, every call from that number needs to be announced — not just the calls you're specifically worried about.
If you turn on Secure Branding for a number before your pre-authorization integration is sending announcements correctly, calls from that number lose their branding immediately — quietly, and on every network, not only the one you were trying to protect. This can look exactly like an attack or a platform fault, when the real cause is that the integration isn't live yet.
If this happens to you: disable Secure Branding for the affected number(s). This restores standard branding straight away. Once your announcement integration is tested and confirmed working — for example, by sending a test announcement and placing a real call to check it displays — you can re-enable Secure Branding. Nothing is lost by doing this, and it's the fastest way back to normal branding while you finish testing.
Secure Branding controls
When Secure Branding is enabled for your account, you can manage phone numbers for Secure Branding under the Secure Branding tab on The Branded Call phone numbers list. In addition, you can manage Secure Branding-related settings for individual phone numbers on their details page by clicking the "EDIT DISPLAY AND SETTINGS" button.
Changing settings for all of your numbers
- When using the "Enable for all numbers" button, Secure Branding will be enabled for every Branded Call phone number in your account.
- When using the "Disable for all numbers" button, Secure Branding will be disabled for every Branded Call phone number in your account.
Changing settings for individual phone numbers
To manage Secure Branding pre-authentication for individual Branded Call phone numbers, go to the "Update Secure Branding for individual phone numbers" section, find and select one or more phone numbers you wish to edit, and click "Enable selected" or "Disable selected".
Spoof protection analytics
You can view spoof protection analytics for calls initiated by your Branded Call phone numbers. If Secure Branding is available for your account, you will see the Secure Branding tab when you click on Call performance under the Branded Call section in the left navigation.
The first section shows Secure Branding usage, which is the count of phone numbers with Secure Branding enabled.
The second section is the spoofed or unauthorized calls, which shows the percentage of outbound calls that were not authorized. You can adjust the period for viewing analytics by clicking on the date picker below the section title. You can view performance week by week, month to month, or day over day.
The last section shows a list of phone numbers that have reported spoofed calls and their spoof rates over a time period. You can select a time period from three options: the last seven days, the last thirty days, or the last three months.