# Accounts API

A buyer account is how traffic reaches TelecomsXchange: a SIP trunk authorised by IP or digest login, an SMPP bind, or an IoT (MQTT) login. Each account has its own balance (or uses another account's), its own purchased routes and its own alerts. Create accounts, change their credentials and authorise extra IP addresses.

## Create a buyer account

`POST https://apiv2.telecomsxchange.com/buyers/account/add`

Reference: https://help.telecomsxchange.com/reference/accounts/#create-a-buyer-account

Creates a buyer account: a voice SIP trunk authorised by IP address, SIP login or both (`smpp=0`), an SMPP bind (`smpp=1`) or an IoT MQTT login (`smpp=2`). Returns the new `i_account`. For voice and SMPP accounts TCXC emails you, and texts you if an SMS number is on file, that a new origination IP or login was registered. Free.

> Send every field in the form body; fields in the query string are ignored.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `name` | string | body | yes | Account name, unique among your accounts. Example `Northwind-SIP`. |
| `smpp` | integer | body | no | Account type: 0 voice (SIP), 1 SMPP, 2 IoT (MQTT). One of `0`, `1`, `2`. Default `0`. Example `0`. |
| `ip_address` | string | body | no | IPv4 or IPv6 address your traffic comes from. Voice accounts need `ip_address`, `voip_login` or both. An IP used for IP-only authentication cannot be shared with another account. Example `203.0.113.25`. |
| `voip_login` | string | body | no | SIP username (voice), SMPP system_id (required when smpp=1) or MQTT username (smpp=2; must start with your customer ID zero-padded to 10 digits, such as 0000001014). Must be unique. Example `nw_sip_01`. |
| `voip_password` | string | body | no | SIP, SMPP or MQTT password for `voip_login`. Example `pw-Xr83kq2L`. |
| `use_balance` | integer | body | no | `i_account` of another of your accounts whose balance this account should spend. 0 gives the account its own balance. Default `0`. Example `0`. |
| `subscribe_all_pr` | integer | body | no | Voice accounts only: 1 adds every unblocked route your other accounts have bought to the new account, with the same ASR and ACD alert and block thresholds. One of `0`, `1`. Default `0`. Example `1`. |

### Errors

| Message | When |
|---|---|
| `You have to specify IP Address or voip_login or both` | a voice account (smpp=0) has neither ip_address nor voip_login |
| `IP should be IP address, say 1.2.3.4` | ip_address is given but is not a valid IPv4 or IPv6 address |
| `IP is not unique` | a voice account without voip_login uses an IP already authorised for IP-only authentication on the exchange |
| `This IP address is already being authenticated` | a voice account without voip_login uses an IP that another voice account already has |
| `Wrong Prefix for login` | smpp=2 and voip_login does not start with your 10-digit zero-padded customer ID |
| `This Login is not unique` | smpp=2 and voip_login is already in use |
| `Empty SMPP system Id not allowed:` | smpp=1 and voip_login is empty |
| `Name is not unique, choose another name` | you already have an account with this name |
| `Empty name not allowed` | name is empty |
| `voip_login is not unique, choose another voip_login<voip_login>` | a voice account's voip_login is already taken; the login follows the message with no space |
| `voip_login is not unique om the ip, choose another voip_login or ip` | an SMPP account with the same system_id and IP already exists |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/account/add" \
  -d name=Northwind-SIP \
  -d smpp=0 \
  -d ip_address=203.0.113.25 \
  -d voip_login=nw_sip_01 \
  -d voip_password=pw-Xr83kq2L \
  -d use_balance=0 \
  -d subscribe_all_pr=1
```

### Response: Example

```json
{
  "status": "success",
  "message": "Account has been added",
  "new_i_account": 2088
}
```

## Update a buyer account

`POST https://apiv2.telecomsxchange.com/buyers/account/edit/{i_account}`

Reference: https://help.telecomsxchange.com/reference/accounts/#update-a-buyer-account

Replaces the settings of one of your accounts: name, IP, login and password, which balance it spends, low-balance alert, block flag and, for SMPP accounts, the default route or routing group. This is a full update: optional fields you leave out are reset, so `blocked` becomes 0, `notification_balance` is cleared, and `smpp_rate_limit`, `default_routing_group` and `subspace` become 0. If the IP address or login changes, TCXC emails you, and texts you if an SMS number is on file. Free.

> Send every field in the form body; fields in the query string are ignored. Send the account's current values for any setting you don't want to change.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `i_account` | integer | path | yes | The account to update. Example `1022`. |
| `name` | string | body | yes | Account name. Example `Northwind`. |
| `use_balance` | integer | body | yes | `i_account` of the account whose balance this one spends, or 0 for its own balance. Example `0`. |
| `ip_address` | string | body | no | IPv4 or IPv6 address. Voice accounts need `ip_address`, `voip_login` or both. Example `203.0.113.10`. |
| `voip_login` | string | body | no | SIP username, SMPP system_id (required for SMPP accounts) or MQTT username. |
| `voip_password` | string | body | no | New password. Leave empty to keep the current one. |
| `blocked` | integer | body | no | Send this field, with any value, to block the account; omit it to leave the account unblocked. A blocked account cannot send traffic. |
| `notification_balance` | number | body | no | Send a low-balance alert when the balance falls below this amount. Empty switches the alert off. Example `1000`. |
| `smpp_rate_limit` | integer | body | no | SMPP accounts: messages-per-second limit for the bind; 0 sets no limit. Default `0`. Example `0`. |
| `default_routing_group` | integer | body | no | SMPP accounts: `i_routing_group` to use by default; must be one of your routing groups. Setting it clears the default purchased route. Default `0`. Example `0`. |
| `smpp_default` | integer | body | no | SMPP accounts: `i_purchased_route` of one of this account's routes to make the default; clears `default_routing_group`. |
| `subspace` | integer | body | no | 1 authenticates calls from the Subspace network by its special header instead of the source IP. One of `0`, `1`. Default `0`. Example `0`. |

### Errors

| Message | When |
|---|---|
| `Unexpected DB error` | i_account is not one of your accounts; returned as plain text, not JSON |
| `You have to specify IP Address or voip_login or both` | a voice or IoT account has neither ip_address nor voip_login |
| `IP should be either IP address, say 1.2.3.4 or host:port like 1.2.3.4:5060` | ip_address is not a valid IPv4 or IPv6 address (host:port is not accepted) |
| `IP is not unique` | a voice account without voip_login uses an IP already authorised for IP-only authentication on another account |
| `'notification_balance' parameter expects numeric` | notification_balance is not empty and not a number |
| `This IP address is already being authenticated` | a voice account without voip_login uses an IP that another voice account has |
| `Empty SMPP system Id not allowed` | an SMPP account's voip_login is empty |
| `rouing group not found` | an SMPP account's default_routing_group is not one of your routing groups |
| `'use_balance' parameter expects integer` | use_balance is missing or not a number |
| `voip_login is not unique, choose another voip_login` | a voice account's voip_login is used by another account |
| `voip_login is not unique on the ip, choose another voip_login` | another SMPP account has the same system_id and IP |
| `Empty name not allowed` | name is empty |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/account/edit/1022" \
  -d name=Northwind \
  -d use_balance=0 \
  -d ip_address=203.0.113.10 \
  -d voip_login='' \
  -d voip_password='' \
  -d notification_balance=1000 \
  -d smpp_rate_limit=0 \
  -d default_routing_group=0 \
  -d subspace=0
```

### Response: Example

```json
{
  "status": "success",
  "message": "Account has been updated"
}
```

## Add an extra IP to an account

`POST https://apiv2.telecomsxchange.com/buyers/account/additional_ip_add/{i_account}`

Reference: https://help.telecomsxchange.com/reference/accounts/#add-an-extra-ip-to-an-account

Authorises one more source IP address for one of your accounts, so traffic from the main IP or any additional IP is accepted for it. Returns the ID of the new IP entry. Free.

> Send `ip_address` in the form body; it is ignored in the query string.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `i_account` | integer | path | yes | The account to add the IP to. Example `1022`. |
| `ip_address` | string | body | yes | IPv4 or IPv6 address to authorise. Example `198.51.100.40`. |

### Errors

| Message | When |
|---|---|
| `Missing i_account` | the path has no i_account, or it is 0 |
| `i_account not found` | the account is not one of yours |
| `IP should be IP address, say 1.2.3.4` | ip_address is missing or not a valid IPv4 or IPv6 address |
| `The IP is already used up` | the account has no voip_login and the IP is already authorised for IP-only authentication on the exchange |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/account/additional_ip_add/1022" \
  -d ip_address=198.51.100.40
```

### Response: Example

```json
{
  "status": "success",
  "message": "IP has been added",
  "new_i_remote_ip_auth": 311
}
```