EasyAnnounce
Developer Hub

EasyAnnounce API

Integrate our name predictions or automated announcement generation with your applications via our secure API gateway.

Gateway Auth

Requests must include Authorization: Bearer YOUR_KEY. Zuplo, our gateway provider, validates this before hitting our ML and TTS workers.

ML & Processing

Name predictions and audio generations work on our secure cloud worker servers. A secure private url is made available to the user or PA system for audio playback.

TTS Engines

Dynamic generations currently use the latest providers in TTS for consistency and clarity.

API Access & Rate Limits

The EasyAnnounce API is available to customers on paid plans only. All requests are rate and quota limited per organization.

  • free = 2 req/min (No API access)
  • starter = 5 req/min
  • pro = 10 req/min
  • enterprise = 25 req/min

These are consolidated total requests per organization per minute, so any webapp usage is included in the total figure alongside API requests.

1. Name Prediction

POST /v1/names/prediction

Analyze names to predict the most likely phonetic language and region origin. The subjects list item can contain either given_name + family_name field, or it can be full_name with the name string fully populated in any order.

Request Example
curl -X POST "https://api-gw.easyannounce.com/v1/names/prediction" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "origin": "NZ",
    "subjects": [{ "given_name": "Paetongtarn", "family_name": "Shinawatra" }]
  }'

2. Audio Preview

POST /v1/names/preview

Generate a temporary audio file for specific names. This uses ElevenLabs TTS to create a preview stored on our CDN for immediate verification.

Request Example
curl -X POST "https://api-gw.easyannounce.com/v1/names/preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "voice": "female-us",
    "subjects": [{ "given_name": "Anutin", "family_name": "Charnvirakul" }]
  }'

3. Full Announcement

POST /v1/announcements/{sector}

The master endpoint. Predicts & stitches name audio, alongside all other required details, into a single high-fidelity announcement. Also triggers automated translation jobs which can be retrieved via a POST to the translation endpoint with the returned job ID.

Request Example
curl -X POST "https://api-gw.easyannounce.com/v1/announcements/{sector}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "origin": "US",
    "sector": "airport",
    "voice": "male-gb",
    "calltype": "finalcall",
    "locationId": "A27",
    "operatorId": "ANZ",
    "transportId": "NZ102",
    "destinationId": "LAX",
    "subjects": [
      { "given_name": "Aiko", "family_name": "Tanaka" },
      { "given_name": "Thao", "family_name": "Nguyen" },
      { "given_name": "Fatima", "family_name": "Al-Zahra" }
    ]
  }'

Payload Fields

origin = the country code where the announcement needs to be made/is being requested from.
voice = the ID or string name of the desired english language announcement, standard voices are: male-gb, male-us, female-gb, female-us. Enterprise customers can have their own customized voice, they can enter their voice ID here.

Note: currently we do not support options for changing the voice of the translated announcement. Please contact us if you would like your translated announcements in a different voice.

sector = the sector your organization belongs to, crucial to obtain the correct announcements. Currently we support: 'airport', 'retail', 'cafe', 'waiting', 'hospital', 'school'.
subjects = a list of each person's name to be said, the list item can either include 'given_name' + 'family_name', just 'full_name', or just 'given_name' (intended for first names only).
calltype = the desired announcement type. E.g. 'finalcall', 'finalcall-group', 'urgentcall', 'lostchild', 'infodesk'. This list is growing, contact us for more details.
locationId = the location aimed at the customer (e.g. the airport gate code, the ward name, the room name).
operatorId = currently airport specific, this would be the ICAO letter code of the airline required for the announcement.
destinationId = currently airport specific, The IATA letter code for the destination airport.
transportId = the IATA flight code of the flight, this will also be included in the announcement.
itemId = Aimed at Retail and Tourism, can be any short string, e.g. "wallet" or "lift pass".