Introduction to the AI Voice Platform APIs
Welcome to the API reference for the Hiya AI Voice Platform. These REST APIs enable carriers to offer advanced call protection services to their subscribers, including intelligent call screening, real-time fraud detection, and voice assistant capabilities.
Base URL for API requests -- https://voiceplatform.api.hiya.com/v1
Overview
The Hiya AI Voice Platform provides the following capabilities:
| Capability | Description |
|---|---|
| Call Screening | AI-powered assistant that answers calls, identifies callers, and filters unwanted calls |
| Deepfake Protection | Real-time synthetic voice and AI-generated speech detection to identify fraudulent callers |
| In-Call Whisper Warnings | Audio alerts delivered to the subscriber during live calls when fraud or scam intent is detected |
| Real-time Analysis | Live call monitoring with fraud detection and scam warnings |
| Decoy Bot | Time-wasting engagement bot that keeps scammers occupied while protecting real users |
| Contact Management | Privacy-preserving contact synchronization |
| User Preferences | Granular control over call handling behavior |
| Consent Management | Independent audit trails for security setting changes to support regulatory compliance |
Authentication
All endpoints require JWT bearer token authentication. Tokens are obtained by exchanging carrier OIDC tokens through the /v1/auth/token endpoint.
Authentication Flow
- The client application authenticates users using the carrier's OpenID Connect (OIDC) identity provider
- The resulting OIDC access token is presented to Hiya's backend via the
/v1/auth/tokenendpoint - Hiya validates the token (issuer, audience, signature, and claims) and performs a token exchange
- A short-lived Hiya-scoped JWT is minted and returned to authorize subsequent API calls
Carrier Integration
The platform integrates with carrier networks via SIP as a Back-to-Back User Agent (B2BUA), using the X-Hiya-Call-Screening-Action header to specify call handling:
| Header Value | Behavior |
|---|---|
screen | Route to AI assistant for caller screening |
analyze | Anchor media for real-time fraud analysis with whisper warnings |
decoy | Route to scam engagement bot |
default | Hiya determines best action to take based on intelligence and user preferences |
The platform is designed with fail-open architecture to ensure calls are never blocked due to system unavailability.
API Categories
Authentication
Exchange carrier OIDC tokens for Hiya JWT tokens to authorize API requests.
Call Management
Access call history, screening results, and provide feedback on calls.
User Preferences
Configure AI assistant behavior, security settings, personal block/allow lists, and call handling preferences.
Contact Sync
Privacy-preserving address book synchronization using hashed and salted contact data.
Phone Lookup
Query caller ID and reputation data for phone numbers.
Live Calls
WebSocket streaming for real-time call events and status updates.
Audit Log
Access independent audit trails for security and privacy-related user settings, supporting consent management and regulatory compliance (CCPA, FTC, FCC).