> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Organization Status

> Suspends or reactivates an organization

Suspends or reactivates an organization with an API key. Account-wide keys can change any organization in the account, and reseller-scoped keys only organizations under their reseller. Organization-scoped keys are refused with `403` `insufficient_scope`, so an organization cannot reactivate itself. In the dashboard, account admins and Reseller Admins use the Customers page instead. See [Suspending an organization](https://docs.telzino.com/event-webhooks/events.md#suspending-an-organization) for what a suspension does.

## Path Parameters

**organization\_id** `string` *required*

The unique identifier of the organization

## Request Body

**status** `string` *required*

`active` or `suspended`.

**suspended\_reason** `string`

Optional reason, up to 500 characters, sent as `reason` in the `org.suspended` event. Ignored when reactivating: the reason is cleared.

No other fields are accepted: an unknown field returns `400` `invalid_request`.

While suspended, inbound phone and web calls to the organization's agents are refused, new outbound calls return `409` `ORG_SUSPENDED` and queued outbound calls are skipped, and SMS from its agents is refused. Billing is unchanged.

A change of status fires the `org.suspended` or `org.reactivated` [event](https://docs.telzino.com/event-webhooks/events.md). Sending the status the organization already has changes nothing: the current row is returned and no event is sent.

```bash cURL theme={null}
curl -X PATCH "https://api.telzino.com/v1/organizations/3f2b8c1e-5d4a-4e7b-9c2d-1a6f0e8b7d54" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "suspended",
  "suspended_reason": "Unpaid invoice"
}'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.telzino.com/v1/organizations/3f2b8c1e-5d4a-4e7b-9c2d-1a6f0e8b7d54', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "status": "suspended",
    "suspended_reason": "Unpaid invoice"
  })
});
```

```python Python theme={null}
import requests

response = requests.patch(
    'https://api.telzino.com/v1/organizations/3f2b8c1e-5d4a-4e7b-9c2d-1a6f0e8b7d54',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
    json={
      "status": "suspended",
      "suspended_reason": "Unpaid invoice"
    }
)
```

```json 200 theme={null}
{
  "id": "3f2b8c1e-5d4a-4e7b-9c2d-1a6f0e8b7d54",
  "status": "suspended",
  "suspended_at": "2026-10-21T14:05:00Z",
  "suspended_by": "api_key:7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "suspended_reason": "Unpaid invoice"
}
```

```json 400 theme={null}
{
  "error": "invalid_request",
  "error_description": "Invalid request body"
}
```

```json 403 theme={null}
{
  "error": "insufficient_scope",
  "error_description": "This API key is limited to a single reseller or organization and cannot call this endpoint."
}
```

```json 404 theme={null}
{
  "error": "not_found",
  "error_description": "Organization not found"
}
```

## Response

`id`, `status`, `suspended_at`, `suspended_by` (the [actor](https://docs.telzino.com/event-webhooks/events.md#actor) who made the change, kept after reactivating) and `suspended_reason`. Reactivating sets `suspended_at` and `suspended_reason` to `null`.

## Error codes

| Code | `error` | Meaning |
| - | - | - |
| `400` | `invalid_request` | `organization_id` is not a UUID, or the body is invalid (missing or unknown `status`, an unknown field, or `suspended_reason` over 500 characters). A body error also returns `details`. |
| `401` | `unauthorized` | Missing or invalid API key |
| `403` | `insufficient_scope` | The key is scoped to a single organization |
| `404` | `not_found` | The organization does not exist or is outside the key's scope |
| `500` | `internal_error` | The change could not be saved |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.