Skip to main content

​
Settings API

Everything that shows up under the dashboard’s Settings tab — the organization profile, user preferences, in-app notifications, team & invites, API keys, sender IDs, single sign-on (SAML & SCIM), HIPAA controls, privacy, compliance policies, and keyword / opt-out rules. Base path: /api/v1/settings Authentication: Session JWT (most operations are admin/owner-gated).

​
Organization

​
User preferences

​
Notifications

​
Team

​
API keys

​
Sender IDs

Many countries require sender ID pre-registration before alpha-numeric sender IDs can be used. The full list of operations (including delete + status checks) is in the auto-generated reference below.

​
Single sign-on (SAML & SCIM)

Configure enterprise SSO and directory provisioning for the org. These endpoints manage the configuration; the login and provisioning flows your identity provider calls live on the public /auth/saml/* and /scim/v2/* paths documented under Authentication. The SSO URL and metadata URL are validated to block requests to internal or private addresses. When you configure SAML for the first time, PATCH /api/v1/settings/saml requires an x509Cert; once one is stored, omit the field to change other settings without re-uploading it.

​
HIPAA controls

Manage covered-entity mode, the Business Associate Agreement (BAA) record, and the PHI access log. Reads require an admin; enabling, disabling, and BAA changes are owner only. Disabling HIPAA mode is protected. PUT /api/v1/settings/hipaa with enabled: false returns 401 REAUTH_REQUIRED unless you first call POST /api/v1/settings/hipaa/reauth-challenge and replay the returned token in an X-Reauth-Challenge header within 5 minutes. Enabling HIPAA and retention-only updates do not require re-auth. See HIPAA compliance for the full covered-entity guide.

​
Privacy

Control PII redaction and transcript retention for the org. Reads are available to any member; updates are owner/admin only. The body of PUT /api/v1/settings/privacy accepts:
  • pii_redaction_enabled (boolean) — mask phone numbers and email addresses on screen for viewer-tier operators. Display only; dial targets and outbound payloads still carry raw E.164.
  • pii_redaction_in_transcripts (boolean) — scrub PII from agent conversation turns at write time. Applies to new turns only; existing turns are not back-redacted.
  • transcript_retention_days (integer 1–3650, or null for no deletion) — the nightly retention job deletes agent conversations and messages older than this window.

​
Compliance

Per-org compliance and outbound-safety policies enforced on the send path. Each resource exposes a read (available to any member) and a write (owner only). The country allowlist is tenant-scoped — it constrains only your own org’s outbound traffic, never another tenant’s.

​
Keyword & opt-out rules

Automated inbound-keyword handling and STOP/START opt-out management. Keyword-rule writes require the developer role or higher; opt-out-rule writes require an admin. Both list endpoints are paginated.

​
Keyword rules

A rule matches an inbound keyword on a channel (sms, whatsapp, rcs, viber, email) with a match_type of exact, contains, starts_with, or regex, then runs an action: reply with response_text, forward to an agent_id, trigger a flow_id, or opt the contact out / back in.

​
Opt-out rules

Opt-out rules are keyword rules whose action is opt-out or opt-in (for example STOP and START). Set auto_reply_text to confirm the change back to the contact. See Opt-outs & suppression for how suppression is enforced at send time.

​
See also