aethexDocs
Dashboard

API Reference

Do-not-call list

Numbers this tenant must never be dialled to. Checked before every outbound call — POST /calls/trigger, POST /calls/batch, the Teams and WhatsApp call paths, and every target an in-call transfer would dial — so an entry here is a guarantee rather than a request. A batch does not fail because some recipients are suppressed; those recipients come back skipped.

Base URL
https://api.aethexai.com/api/v1
Endpoints
6
Scopes
call_suppressions:readcall_suppressions:write
POST/suppressions

Stop this number from ever being dialled.

Suppress a number

Idempotent: suppressing a number that is already on the list returns the existing entry rather than an error, so a client re-syncing its whole list can replay this endpoint safely. Numbers may be written the way a person types them — +1 (415) 555-1234 is accepted and stored under a canonical key.

Request body

3
  • numberstringrequired

    Destination to suppress. E.164; common punctuation is accepted and stripped.

  • sourcestringoptional

    Where the entry came from: api, operator, carrier or import. Defaults to api.

  • reasonstringoptional

    Free-text note, up to 500 characters. Shown back on the entry.

Errors

1
422Unprocessable Entity

The value is not a phone number once punctuation is removed, or source is not one you may set.

Send an E.164 number, and leave source unset unless you are recording an import or an operator action.

POST/suppressions/bulk

Add up to 1,000 numbers in one request.

Suppress many numbers

The response distinguishes new entries from numbers already on the list, so a re-sync can tell what actually changed. All-or-nothing: a request that fails leaves the list untouched, rather than applying half of it.

Request body

3
  • numbersstring[]required

    Destinations to suppress. 1–1,000 entries.

  • sourcestringoptional

    Where the entry came from: api, operator, carrier or import. Defaults to api.

  • reasonstringoptional

    Free-text note, up to 500 characters. Shown back on the entry.

GET/suppressions

This tenant's entries, newest first.

List suppressions

Released entries are hidden unless you ask for them. This does not include customers who opted out by texting STOP — those suppress calls too but have no entry here. Use the check endpoint to ask about one number across both.

Path & Query

5
  • sourcestringoptional

    Return only entries with this source.

  • include_releasedbooleanoptional

    Include released (lifted) entries. Defaults to false.

  • offsetintegeroptional

    Rows to skip. Defaults to 0.

  • limitintegeroptional

    Rows to return, 1–200. Defaults to 50.

GET/suppressions/check

Would a call to this number be refused, and why?

Check a number

The authoritative answer, across both this list and SMS opt-outs. A number whose source is sms_opt_out is suppressed because the customer replied STOP to one of your numbers; it will not appear in the list endpoint, which is why this exists alongside it. number is validated as the create endpoint validates it, so a mistyped number answers 422 rather than suppressed: false.

Path & Query

1
  • numberstringrequired

    Destination to check, E.164.

GET/suppressions/:suppression_id

Retrieve one entry by id.

Get a suppression

Returns released entries as well as live ones, so an entry that was lifted can still be inspected.

Errors

1
404Not Found

No suppression with that id belongs to this tenant.

List the suppressions to find the id, or check you are using the right API key.

POST/suppressions/:suppression_id/release

Allow this number to be dialled again.

Release a suppression

Lifts the suppression without deleting the record — the entry remains retrievable with include_released=true, because it is the evidence you were entitled to stop calling that person. Entries that record something the customer said cannot be released here: a number suppressed because they asked you to stop, or because they texted STOP, is not yours to un-say.

Errors

2
403Forbidden

The entry records a request from the customer (callee_request, or an SMS STOP).

Nothing to fix from the API. That suppression can only be lifted by the customer opting back in.

404Not Found

No suppression with that id belongs to this tenant.

List the suppressions to find the id, or check you are using the right API key.