# Organization Settings

> Read and update organization settings and upload calling audio

Source: https://docs.soosh.io/reference/api/org-settings/

## Overview

These endpoints manage the current organization's settings — general preferences, calling behaviour, and the audio files used for hold music and ringback. Settings are stored per-organization and always scoped to the caller's org. For org CRUD and membership, see the [Organizations API](https://docs.soosh.io/reference/api/organizations).

## Get Settings

Return the current organization's settings and name. Values fall back to server defaults (and the global `[calling]` config) when unset.

`GET /api/org/settings`

### Response

```json
{
  "status": "success",
  "data": {
    "settings": {
      "mask_phone_numbers": false,
      "timezone": "UTC",
      "date_format": "YYYY-MM-DD",
      "calling_enabled": false,
      "max_call_duration": 3600,
      "transfer_timeout_secs": 60,
      "hold_music_file": "",
      "ringback_file": ""
    },
    "name": "Acme Inc"
  }
}
```

### Settings Fields

**General**

| Field | Type | Description |
|-------|------|-------------|
| `mask_phone_numbers` | boolean | Mask contact phone numbers (and phone-like names) across the app and exports. |
| `timezone` | string | Display timezone (default `UTC`). |
| `date_format` | string | Date display format (default `YYYY-MM-DD`). |

**Calling**

| Field | Type | Description |
|-------|------|-------------|
| `calling_enabled` | boolean | Enable WebRTC voice calling for the organization. |
| `max_call_duration` | integer | Maximum call length in seconds. |
| `transfer_timeout_secs` | integer | Seconds to wait for an agent to accept a transfer. |
| `hold_music_file` | string | Filename of the uploaded hold-music track. |
| `ringback_file` | string | Filename of the uploaded ringback tone. |

## Update Settings

Update one or more settings. All fields are optional — only the fields present in the body are changed.

`PUT /api/org/settings`

### Request Body

```json
{
  "name": "Acme Inc",
  "mask_phone_numbers": true,
  "timezone": "America/New_York",
  "date_format": "MM/DD/YYYY",
  "calling_enabled": true,
  "max_call_duration": 1800,
  "transfer_timeout_secs": 45,
  "hold_music_file": "org_<id>_hold_music.ogg",
  "ringback_file": "org_<id>_ringback.ogg"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Organization name (ignored if empty). |
| `mask_phone_numbers` | boolean | Toggle phone masking. |
| `timezone` | string | Display timezone. |
| `date_format` | string | Date display format. |
| `calling_enabled` | boolean | Enable/disable calling. |
| `max_call_duration` | integer | Max call seconds (applied only when > 0). |
| `transfer_timeout_secs` | integer | Transfer accept timeout (applied only when > 0). |
| `hold_music_file` | string | Hold-music filename (usually set via the audio upload below). |
| `ringback_file` | string | Ringback filename (usually set via the audio upload below). |

> **Note:** Changes are recorded to the audit trail as `settings.general` and `settings.calling` entries. The Meta app used for Embedded Signup is platform-wide and managed by super admins via `GET`/`PUT /api/admin/platform/meta-app`.

### Response

```json
{
  "status": "success",
  "data": {
    "message": "Settings updated successfully"
  }
}
```

## Upload Calling Audio

Upload an audio file for hold music or ringback. The file is transcoded to OGG/Opus (48 kHz mono) for WebRTC playback, stored, and the matching `hold_music_file` / `ringback_file` setting is updated automatically.

`POST /api/org/audio`

Requires the `organizations:write` permission.

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | `hold_music` or `ringback`. |

### Form Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | file | Yes | Audio file, max 5 MB. Accepts OGG, Opus, MP3, and WAV. |

### Response

```json
{
  "status": "success",
  "data": {
    "filename": "org_<id>_hold_music.ogg",
    "type": "hold_music",
    "mime_type": "audio/mpeg",
    "size": 204800
  }
}
```

## See Also

- [Organizations API](https://docs.soosh.io/reference/api/organizations) - Organization CRUD and members
- [Calling](https://docs.soosh.io/features/calling) - WebRTC voice calling, hold music, and transfers