# Create Power2 sub account with credit transfer

`POST /api/communications/sms/create-account`

- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Create Power2 sub account with credit transfer](https://support.gladstonesoftware.cloud/reference/communications/create-power2-sub-account-with-credit-transfer)

## Overview

Sets a tenant up to send text messages. The call creates a sub-account under Gladstone's account with Power2 — the third-party gateway used for SMS — transfers 50 credits into it from the main account, and records the resulting sub-account name and sender id in the tenant's configuration so that every later SMS call uses them.

Treat this as one-time setup, and note that it is not idempotent: each call creates another sub-account and repoints the tenant's configuration at the newest one. The sub-account is named after the operator's trading name where one is configured, or `P2SA-` plus three random letters where it is not; if Power2 reports that name is already taken, a `_1`, `_2` … suffix is appended until one is free, so the name you end up with is not necessarily the one you would predict.

A `200` does not mean it worked. Failures at Power2 are reported in the body rather than as an error status: check `account.status` for the sub-account and `credit.status` for the credit transfer, each with a `message` explaining a `false`. If the sub-account could not be created, the transfer is not attempted and `credit.message` reads `No credits were transferred.`

Once this has succeeded, [Get SMS account balance](get-sms-account-balance.md) reports the credits held by the new sub-account.

## Endpoint

`POST {base_url}/api/communications/sms/create-account`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `originator` | string | Yes | The sender id recipients see in place of a phone number on texts from this tenant. Must be 3 to 11 characters once surrounding whitespace is trimmed; `null`, empty and whitespace-only values are each rejected with their own message. The value is stored in the tenant's configuration and reused for every later send and for the balance lookup, so it stays in force until this call is made again. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/communications/sms/create-account' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "originator": "string"
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `originator` is absent (`Originator in request body is missing.`), empty or whitespace only (`There is an empty originator in the request.`), or outside 3 to 11 characters (`The originator must be 3 to 11 characters long.`). Also returned when the tenant's SMS account details could not be assembled (`Failed to retrieve SMS account details.`). |
| `404` | Not found | The environment has no Power2 credentials configured — user name, secret key or main account name is missing (`Attempting to retrieve Power2Sms user name but the user name does not exist.`). |
| `500` | Internal server error | An unexpected failure while calling Power2 or interpreting its answer. Note that a Power2 refusal is not reported here: it comes back as `200` with `account.status` or `credit.status` set to `false`. |

## Notes

- The sub-account name and sender id this call saves can take up to 20 minutes to be picked up by the other SMS endpoints. Until then, [Get SMS account balance](get-sms-account-balance.md) can still return `404` (on a first set-up) or report the balance of the previous sub-account (when the call is repeated). Wait 20 minutes after a successful call before you check the balance.
- Each successful call transfers 50 credits to the new sub-account, and the transfer is not reversed if you call again or abandon the sub-account.