Announce outbound call
POST/v1/originators
Announces an outbound call to Hiya before it is placed, so Hiya can pre-authenticate it and apply Secure Branding in real time. A call that reaches Hiya's network without a matching, unexpired announcement is treated as unauthenticated and will not receive Secure Branding.
An announcement is matched to the real-world call using originatingPhone and terminatingPhone, and remains valid for timeToLiveSeconds after Hiya receives it. If the call is not placed within that window, the announcement expires and the call will not be pre-authenticated.
For setup steps, recommended call-flow timing, and monitoring, see the Secure Your Branded Call from Spoofers guide. This page documents only the request/response contract for this endpoint; For the Authorization header, see Authentication; for the shared error envelope and status codes, see HTTP Error Status Codes.
Body
required
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 410
- 429
- 500
The call announcement was received and processed successfully.
Response Body
Bad Request - A required parameter is missing or has an invalid value.
Response Body
Unauthorized - The API Key is invalid or missing.
Response Body
Forbidden - The API Key doesn't have the necessary authorization to access this resource.
Response Body
Not Found - This API doesn't exist (or has been fully deprecated)
Response Body
Request Timeout - A complete request was not received by the server within its allotted timeout period. It's safe to retry.
Response Body
Gone - You must stop calling this API permanently once you receive this status code
Response Body
Too Many Requests - The number of requests within a given time period was exceeded.
Response Body
Internal Server Error - The server has experienced an unexpected condition and is unable to process the request
Response Body