NUACOM API

Numbers & call routing

Holiday Settings

Holiday settings tell an IVR what to do with a call on a day the business is closed. Each IVR can have one public holiday rule, applied on every national holiday of the country chosen for that IVR, and any number of custom rules, each a single from–to period in the IVR's own timezone. This group holds the public holiday calendar (by country, or grouped by IVR), the public holiday rule (list, update, clear) and the custom rules (list, update, delete, clear). The IVR itself, including the out-of-hours actions a holiday rule can hand the call to, is configured in IVR.

Workflow (what the portal does)

  1. IVRs and their public holiday rule: GET /v2/ivr/public_holiday_settings answers an object keyed by IVR id. Each entry has ivr (id, name, pub_holiday_country) and action: the rule's id, menu_id, first_action, first_action_data, second_action and second_action_data, or only menu_id with first_action and first_action_data set to null when the IVR has no rule.
  2. The calendar: GET /v2/public_holidays/{countryCode} lists the upcoming national holidays of a country (ISO 3166-1 alpha-2, upper case; GB also returns the rows filed under UK), oldest first: id, calendar_date (Y-m-d H:i:s, at midnight), country, menu_time_zone, holiday_name, holiday_description and holiday_type (always National holiday). GET /v2/public_holidays_by_ivr answers the same rows grouped by IVR id, for the country each IVR is set to, past dates included; an IVR without a country gets [].
  3. Set the public holiday rule: PATCH /v2/ivr/public_holiday_settings with one JSON object: menu_id (the IVR id), first_action, the optional first_action_data, second_action and second_action_data, and pub_holiday_country to set or change the IVR's country in the same call. Send the rule's id from step 1 when the IVR already has one. Answers 204.
  4. Custom rules: GET /v2/ivr/custom_holiday_settings answers an object keyed by IVR id with ivr (id, name, time_zone) and rules, each with id, menu_id, from_time, to_time, the four action fields and time_zone.
  5. Add or change custom rules: PATCH /v2/ivr/custom_holiday_settings with a JSON array of rules, each with menu_id, from_time, to_time, menu_time_zone (an IANA name such as Europe/Dublin), first_action and the optional first_action_data, second_action and second_action_data. Add id to change an existing rule, leave it out to add one. Rules are saved one by one, in the order sent. Answers 204.
  6. Remove rules: DELETE /v2/ivr/custom_holiday_settings/{id} deletes one custom rule (404 when it is not one of the account's); DELETE /v2/ivr/{ivrId}/custom_holiday_settings deletes every custom rule of an IVR; DELETE /v2/ivr/{ivrId}/public_holiday_settings deletes the IVR's public holiday rule and leaves pub_holiday_country as it is. All answer 204, also when there was nothing to delete.
# Irish public holidays on IVR 1: play announcement slot 12, then hang up
curl -X PATCH https://api.api-nuacom.com/v2/ivr/public_holiday_settings \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"menu_id": 1, "pub_holiday_country": "IE", "first_action": 1, "first_action_data": "12", "second_action": 0, "second_action_data": null}'
# → 204

# Closed from Christmas Eve lunchtime to the end of St Stephen's Day: out-of-hours routing
curl -X PATCH https://api.api-nuacom.com/v2/ivr/custom_holiday_settings \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '[{"menu_id": 1, "from_time": "2026-12-24 13:00:00", "to_time": "2026-12-26 23:59:59", "menu_time_zone": "Europe/Dublin", "first_action": 0, "first_action_data": null, "second_action": null, "second_action_data": null}]'
# → 204

The custom rule then reads back like this (ISO contract; Dublin is +00:00 in December):

{
  "1": {
    "ivr": {"id": 1, "name": "Main Call Flow", "time_zone": "Europe/Dublin"},
    "rules": [
      {"id": 57, "menu_id": 1, "from_time": "2026-12-24T13:00:00+00:00", "to_time": "2026-12-26T23:59:59+00:00", "first_action": 0, "first_action_data": null, "second_action": null, "second_action_data": null, "time_zone": "Europe/Dublin"}
    ]
  }
}

Actions

On a day the public holiday rule matches, or during the period of a custom rule, the IVR runs the rule's actions instead of its open-hours flow: first_action with first_action_data, then second_action with second_action_data where the first action chains. The ids and the data are the IVR's own action vocabulary (see Actions in IVR); the data is a string of at most 50 characters.

first_action What happens first_action_data
0 Go to out of hours: the call takes the IVR's closed-hours actions –
1 Play a message announcement slot 10–99, uploaded with POST /v2/announcements/upload-audio
2 Dial an extension extension number, from GET /v2/extensions
3 Join a queue queue number (not the queue id), from GET /v2/queues
4 Play a prompt, then dial the number the caller enters announcement slot
6 Go to voicemail mailbox number, from GET /v2/voicemail/mailbox_numbers
8 Forward to a number phone number
9 Go to another IVR IVR id
13 Add a call tag tag ids, comma-separated, from GET /v3/call-tags

second_action: 0 none (hang up), 1 dial an extension, 2 join a queue, 4 dial the number the caller entered, 5 fall through (the IVR's no-key action), 6 voicemail, 8 forward to a number, 9 go to another IVR; second_action_data carries the matching value. The portal offers a second action after 1, 3 and 13 (any of them except 4) and after 4 (only 4); after every other first action it sends second_action as null.

How a holiday rule overrides the IVR

flowchart TD
    call["Call arrives at the IVR"] --> match{"Does today match a public holiday<br/>(IVR's country) or a custom from_time/to_time period?"}
    match -- "yes" --> rule["Run the matching rule's first_action / first_action_data,<br/>then second_action / second_action_data"]
    match -- "no" --> normal["IVR's normal open.actions flow"]
    rule -- "first_action 0 (go to out of hours)" --> closed["IVR's close.actions"]

Dates and timezones

  • A custom rule is one period, from_time to to_time, read as wall-clock times in menu_time_zone. Send Y-m-d H:i:s; a bare Y-m-d means midnight, so a one-day closure is 2026-12-25 00:00:00 to 2026-12-25 23:59:59. Other date-time spellings are parsed, but an offset in the value is dropped rather than applied, and X-Timezone plays no part.
  • There is no recurrence: a custom rule covers its dates once, so a closure that repeats every year needs a new rule each year. Public holidays recur on their own: the public holiday rule applies to every national holiday in the calendar of the IVR's country, and the API has no way to leave individual days out.
  • In the custom list, from_time and to_time follow the account's date contract (see Dates and timezones). On the legacy contract they are 2026-12-24T13:00:00.000000Z: the wall-clock time with a Z that does not mean UTC. On the ISO contract they are 2026-12-24T13:00:00+00:00, with the offset of the IVR's timezone, never the one in X-Timezone. calendar_date on the calendar endpoints is Y-m-d H:i:s at midnight on both contracts.
  • ivr.time_zone in the custom list is the timezone of the IVR's first rule, or the account's timezone when the IVR has no rule. GET /v3/time-zones lists the IANA names.

Roles and access

  • Reading, that is both settings lists and both calendar endpoints, is open to any authenticated user of the account. Every PATCH and DELETE needs an account admin; any other user gets 403 with the body "Forbidden".
  • The ISO dates option only changes the format of from_time and to_time.

Pitfalls

  • The settings lists and the by-IVR calendar are JSON objects keyed by IVR id; an account without IVRs gets [].
  • Send id when changing the public holiday rule. A PATCH without id always inserts, and the list shows only the first rule of each IVR, so the extra row is invisible; DELETE /v2/ivr/{ivrId}/public_holiday_settings removes them all.
  • An id that is not one of the account's rules answers 500 on the public holiday PATCH and 404 on the custom PATCH; in the custom case the rules before it in the array are already saved, as there is no transaction.
  • menu_id must be one of the account's IVRs (422 otherwise), but action ids and data are stored as sent: a wrong id, slot, extension or queue number only shows when a call reaches the rule.
  • menu_time_zone is required but not checked against the IANA list. An invalid name is stored, and on the ISO contract the custom list then fails.
  • from_time and to_time are not compared with each other or with other rules: a period that ends before it starts, or overlaps another rule, is accepted.
  • pub_holiday_country cannot be emptied: null or "" is ignored. To stop public holiday routing on an IVR, clear its rule.
  • GET /v2/public_holidays/{countryCode} lists dates from the current moment, so today's holiday has already dropped off it; GET /v2/public_holidays_by_ivr includes past dates. Both list national holidays only, and an unknown country answers [].
  • GB is merged with UK on the country endpoint only; an IVR's pub_holiday_country must be exactly the country its calendar rows carry.