Data Retention

Data retention is how long NUACOM keeps five kinds of account data — call logs, SMS history, call recordings, fax data and voicemail messages — before they are deleted. The account holds one retention interval per type, each bounded by a limit set by the data retention add-on it has. This group holds the settings (read and save), the add-on switch, the two endpoints that resolve a pending reduction — activate it now or cancel it. The data the policy acts on is what Call Logs, Call Recording and Fax serve.

Workflow (what the portal does)#

1. Read the policy: GET /v2/data-retention/settings answers one object per type — call_logs, sms_history, call_recording, fax_data, voicemail — with current (the interval in force), pending (a shorter interval waiting for its grace period, otherwise null) and limit (the longest the account's add-on allows), all as ISO 8601 durations (P1Y, P6M, P30D). Around them: mailboxes, the voicemail intervals of the mailboxes that have their own, keyed by mailbox number ([] when none has one); extensions_count, the number of extensions on the account, which is the quantity an add-on is billed for; is_blocked, true while a change is pending; early_retention_alert, always false; and updated_at, when the pending change was made, null without one. On an account that has never saved settings every current is null.
2. Choose the add-on: POST /v2/data-retention/change-addon with code: none, 3y, 7y or 10y. It cancels the current data retention add-on, activates the requested one and bills the difference as described in Limits and billing. A current interval longer than a new limit is scheduled down to it: the cut value becomes pending and follows step 3, and the add-on you left is remembered for 7 days so that step 5 can bring it back. 204.
3. Save the intervals: POST /v2/data-retention/settings with call_logs_retention_interval, sms_history_retention_interval, call_recording_retention_interval and fax_data_retention_interval — ISO 8601 durations, each at most its limit — and voicemail_retention_interval, an object whose key "null" carries the account-wide voicemail interval (at most P1M, read as 30 days) and whose other keys are mailbox numbers with an interval of their own, which may not be longer than the account-wide one (GET /v2/voicemail/mailbox_numbers lists the numbers). The portal sends all five values every time; do the same (see Pitfalls). The answer is 204 either way, but what happens depends on the direction:
   • every value equal to or longer than today's: the new values are in force at once;
   • any value shorter: every account-wide value in the request becomes pending and the current ones stay in force for a grace period of 7 days, after which a daily run at 06:10 Irish time applies them. An email announcing the new policy goes to the account's primary contact, with the account admins in copy, when the change is made and again when it is applied;
   • mailbox values are saved at once, whichever the direction.
4. Activate now: PATCH /v2/data-retention/settings/activate-now makes the pending values current without waiting; mailbox intervals longer than the new account-wide voicemail interval are cut down to it. No email is sent. 204.
5. Cancel: PATCH /v2/data-retention/settings/cancel discards the pending values; the current ones stay. When the pending change came from an add-on change in the last 7 days, the add-on you had before is activated again, charged from the next month. 204.

curl -X POST 'https://api.api-nuacom.com/v2/data-retention/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "call_logs_retention_interval": "P1Y",
    "sms_history_retention_interval": "P1Y",
    "call_recording_retention_interval": "P3M",
    "fax_data_retention_interval": "P6M",
    "voicemail_retention_interval": {"null": "P1M", "100": "P14D"}
  }'

The recording interval was shortened, so the settings now read:

{
  "call_logs": {"pending": "P1Y", "current": "P1Y", "limit": "P1Y"},
  "sms_history": {"pending": "P1Y", "current": "P1Y", "limit": "P1Y"},
  "call_recording": {"pending": "P3M", "current": "P6M", "limit": "P6M"},
  "fax_data": {"pending": "P6M", "current": "P6M", "limit": "P6M"},
  "voicemail": {"pending": "P1M", "current": "P1M", "limit": "P1M"},
  "mailboxes": {"100": "P14D"},
  "extensions_count": 12,
  "is_blocked": true,
  "early_retention_alert": false,
  "updated_at": "2026-10-29T08:12:45.000000Z"
}

Limits and billing#

code	Call logs	SMS history	Call recording	Fax data	Voicemail
none	P1Y	P1Y	P6M	P6M	P1M
3y	P3Y	P3Y	P3Y	P3Y	P1M
7y	P7Y	P7Y	P7Y	P7Y	P1M
10y	P10Y	P10Y	P10Y	P10Y	P1M

An interval may be anything up to the limit; the voicemail limit is the same with every add-on. A value above the limit answers 422 with Restricted values above the limit, a string that is not a duration with … is not an interval, and a mailbox value above the account-wide one with Voicemail retention for mailbox can not be more than Account Voicemail setting.

Add-ons are priced per extension per month, which is why the settings carry extensions_count. Moving to a dearer add-on refunds the unused part of the month for the old one and charges the new one pro rata for the rest of the month (the full month when you switch on the 1st) plus the next month. Moving to a cheaper one gives no refund and charges from the next month. none cancels the current add-on and charges nothing.

Pending changes#

A pending value is recorded but not in force: the current one keeps applying, is_blocked is true and updated_at says when the change was made. The pending values become current 7 days later, at the next daily run (06:10 Irish time), or at once when you call activate-now; cancel drops them. The API stores the policy; a separate retention process applies it to the stored data and deletes, per type, what is older than the current interval. The API itself deletes nothing and reports no progress.

How a retention change takes effect#

stateDiagram-v2
    [*] --> Current: POST /v2/data-retention/settings, value >= today's (in force at once)
    [*] --> Pending: POST /v2/data-retention/settings, value shorter (is_blocked: true)
    Pending --> Current: daily run at 06:10 Irish time, 7 days later
    Pending --> Current: PATCH /v2/data-retention/settings/activate-now (skips the wait)
    Pending --> Current: PATCH /v2/data-retention/settings/cancel (pending dropped, current unchanged)

Roles and access#

• Every endpoint in this group is for account admins: any other user gets 403 with the body "Forbidden", a missing or invalid token 401 "Unauthorized". Every call is written to the account's change log.
• updated_at is an ISO 8601 UTC timestamp (2026-10-29T08:12:45.000000Z). On an account without the ISO dates option it is the current time instead of null when nothing is pending.

Pitfalls#

• 204 does not say whether the change applied or is pending: read the settings back and look at is_blocked and pending.
• Any shorter value makes every account-wide value in that request pending, the ones you raised included.
• The API does not refuse a second change while one is pending; the portal does (it blocks the form while is_blocked is true). Cancel or activate the pending change first, or the settings answer becomes ambiguous.
• Call activate-now only while is_blocked is true: without a pending change it archives the current values, and every current reads null until you save again.
• Durations are compared with a 30-day month and a 360-day year: P12M equals P1Y, P365D exceeds it, and the voicemail limit P1M admits P30D but not P31D.
• A mailbox value is checked against the account-wide voicemail interval already saved, not the one in the same request. Raise the account-wide value in one request and the mailbox values in the next.
• Sending the code of the add-on already active is not a no-op: it cancels and re-activates the add-on, with a new pro-rata charge for the rest of the month.
• Saving settings or activating now forgets the add-on that cancel could restore; a later cancel only drops pending values.
• A reduction emails the account's primary contact; an increase, activate-now and cancel send nothing.