---
title: "Create a sub-account"
method: POST
path: "/v1/sub-organizations"
tags: ["Sub-accounts"]
---

# Create a sub-account

`POST /v1/sub-organizations`

## Request

- Base URL: `https://api.wavix.com`
- URL: `https://api.wavix.com/v1/sub-organizations`
- Auth: HTTP bearer

Creates a sub-account under the authenticated master account. Returns the sub-account with its generated `api_key`.

## Request body

- SubAccountsCreateRequest
  - `name` string, required: Sub-account name.
  - `default_destinations` object: Default webhook URLs for inbound messages and delivery reports.
    - `sms_endpoint` string, uri: Inbound messages webhook URL.
    - `dlr_endpoint` string, uri: Delivery report webhook URL.

## Response `200`

Returns the created sub-account.

- SubOrganizationResponse: Sub-account details including API key and webhook configurations.
  - `id` integer, required: Sub-account ID.
  - `created_at` string, date-time, required: Date and time the sub-account was created in ISO 8601 format.
  - `name` string, required: Sub-account name.
  - `api_key` string, required: Sub-account API key.
  - `master_organization` integer, required: Master account ID.
  - `status` 'enabled' | 'disabled', required: Status of the subaccount. One of `enabled` (the subaccount is active and can be used) or `disabled` (the subaccount is suspended).
  - `default_destinations` object, required: Default webhook URLs for inbound messages and delivery reports.
    - `sms_endpoint` string, uri, required: Inbound messages webhook URL.
    - `dlr_endpoint` string, uri, required: Delivery report webhook URL.

## Other responses

- `400`: Returns when a required parameter is missing or invalid.
- `401`: Unauthorized
- `403`: Request failed. The feature is disabled for your account.
- `422`: Validation error

## Changes

- **2026-10-14** `e8858666097f`: 1 breaking
  - the `name` request property's maxLength was decreased to `75`
- **2026-09-08** `6a89c962481c`: 1 info
  - added the non-success response with the status `401`
- **2026-06-15** `76b9bb35619f`: 1 info
  - added the optional property `success` to the response with the `422` status
- **2026-05-25** `33be77905120`: 1 info
  - the endpoint scheme security `bearerAuth` was added to the API
- **2026-04-20** `2e48fd9894e1`: 1 info
  - api operation id `Createuser` removed and replaced with `sub_accounts_create`

[Operation history](https://skmtc.dev/wavix/apis/wavix-apis/changes/v1/sub-organizations/post.md)

---

[API](https://skmtc.dev/wavix/apis/wavix-apis.md) - [All operations](https://skmtc.dev/wavix/apis/wavix-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/wavix/apis/wavix-apis/revisions/f2dde79f05ab?raw)