---
title: Settings API
description: Read and update workspace configuration via the Seal REST API
---

# Settings API

The Settings API lets you read and update your workspace's configuration programmatically. Settings are organized into four categories: signing behavior, email notifications, AI features, and security.

## The Settings Object

### Attributes

```json
{
  "signing": {
    "allowed_signature_types": ["draw", "type", "upload"],
    "default_deadline_days": 30,
    "esign_consent_text": null
  },
  "notifications": {
    "reminder_schedule": [3, 7, 14],
    "expiration_alert_days": 3,
    "send_completion_email": true,
    "send_viewed_notification": true
  },
  "ai": {
    "enabled": false,
    "auto_analyze": false
  },
  "security": {
    "ip_allowlist": [],
    "allow_api_access": true,
    "require_mfa": false,
    "session_timeout_minutes": null
  }
}
```

### Signing Settings

| Field                     | Type     | Description                                                           |
| ------------------------- | -------- | --------------------------------------------------------------------- |
| `allowed_signature_types` | string[] | Accepted methods: `draw`, `type`, `upload`                            |
| `default_deadline_days`   | number   | Days until a sent document expires (1–365, default 30)                |
| `esign_consent_text`      | string   | Custom ESIGN Act consent text shown before signing (`null` = default) |

### Notification Settings

| Field                      | Type     | Description                                                    |
| -------------------------- | -------- | -------------------------------------------------------------- |
| `reminder_schedule`        | number[] | Days after sending to auto-send reminders (e.g., `[3, 7, 14]`) |
| `expiration_alert_days`    | number   | Days before deadline to send an expiration warning (1–30)      |
| `send_completion_email`    | boolean  | Notify the document owner when all parties have signed         |
| `send_viewed_notification` | boolean  | Notify the owner when a recipient opens the document           |

### AI Settings

| Field          | Type    | Description                                       |
| -------------- | ------- | ------------------------------------------------- |
| `enabled`      | boolean | Whether AI features are enabled for the workspace |
| `auto_analyze` | boolean | Automatically analyze new documents with AI       |

### Security Settings

| Field                     | Type     | Description                                                  |
| ------------------------- | -------- | ------------------------------------------------------------ |
| `ip_allowlist`            | string[] | Allowed IP ranges in CIDR notation (empty = all IPs allowed) |
| `allow_api_access`        | boolean  | Whether API key access is enabled for the workspace          |
| `require_mfa`             | boolean  | Require multi-factor authentication for all members          |
| `session_timeout_minutes` | number   | Session timeout in minutes (`null` = browser default)        |

## Get Settings

Retrieve the current workspace configuration.

### Endpoint

```
GET /api/v1/settings
```

### Required Scope

`seal:settings:read`

### TypeScript Example

```typescript
const response = await fetch("https://api.seal.nyc/api/v1/settings", {
  headers: {
    Authorization: "Bearer ak_your_api_key_here",
  },
});

const settings = await response.json();
console.log(settings.signing.default_deadline_days); // 30
```

### cURL Example

```bash
curl -X GET "https://api.seal.nyc/api/v1/settings" \
  -H "Authorization: Bearer ak_your_api_key_here"
```

### Response

```json
{
  "signing": {
    "allowed_signature_types": ["draw", "type", "upload"],
    "default_deadline_days": 30,
    "esign_consent_text": null
  },
  "notifications": {
    "reminder_schedule": [3, 7, 14],
    "expiration_alert_days": 3,
    "send_completion_email": true,
    "send_viewed_notification": true
  },
  "ai": {
    "enabled": false,
    "auto_analyze": false
  },
  "security": {
    "ip_allowlist": [],
    "allow_api_access": true,
    "require_mfa": false,
    "session_timeout_minutes": null
  }
}
```

## Update Settings

Update workspace configuration. All fields in all categories are optional — only the fields you include are changed. Categories you omit are left untouched.

### Endpoint

```
PATCH /api/v1/settings
```

### Required Scope

`seal:settings:write`

### Request Body

All fields are optional. Include only the categories and fields you want to change.

```json
{
  "signing": {
    "allowed_signature_types": ["draw", "type"],
    "default_deadline_days": 14,
    "esign_consent_text": "I agree to sign this document electronically."
  },
  "notifications": {
    "reminder_schedule": [3, 7],
    "expiration_alert_days": 5,
    "send_completion_email": true,
    "send_viewed_notification": false
  },
  "ai": {
    "enabled": true,
    "auto_analyze": true
  },
  "security": {
    "ip_allowlist": ["10.0.0.0/8", "192.168.1.0/24"],
    "allow_api_access": true,
    "require_mfa": false,
    "session_timeout_minutes": 480
  }
}
```

### TypeScript Example

```typescript
// Update only signing settings — everything else is preserved
const response = await fetch("https://api.seal.nyc/api/v1/settings", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer ak_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    signing: {
      default_deadline_days: 14,
      allowed_signature_types: ["draw", "type"],
    },
  }),
});

const result = await response.json();
// { "success": true }
```

### cURL Example

```bash
curl -X PATCH "https://api.seal.nyc/api/v1/settings" \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": {
      "send_viewed_notification": false
    }
  }'
```

### Response

```json
{
  "success": true
}
```

> **Info**
>
> **Partial updates**: You can update a single field inside a category without
> specifying the rest. For example, setting only `signing.default_deadline_days`
> leaves `allowed_signature_types` and `esign_consent_text` unchanged.

> **Warn**
>
> **Clearing a field**: To clear `esign_consent_text` or
> `session_timeout_minutes`, pass `null` explicitly. Omitting the field
> preserves the current value.

## Next Steps

- **[Members API](/docs/api-reference/members)** - View workspace members
- **[Audit Log API](/docs/api-reference/audit-log)** - Audit setting changes
- **[Documents API](/docs/api-reference/documents)** - Manage documents