Help Center SMSBAT Client & Wallet Management REST API

SMSBAT Client & Wallet Management REST API

REST API documentation for managing client organizations, contracts, SMS Alpha Name registration applications, wallet balances, transaction histories, and exporting SMS usage statistics.

1. Overview & Authentication

1.1 Base URL

https://restapi.smsbat.com/api

1.2 Authentication

All endpoints require HTTP Basic Authorization:

Authorization: Basic base64(login:password)

1.3 Data Format

Content-Type: application/json (unless specified otherwise, e.g. ZIP downloads)
Encoding: UTF-8
Timestamps: ISO 8601 strings in UTC.

1.4 HTTP Status Codes

Code	Description
200	Success
400	Bad Request / Invalid parameters
401	Unauthorized / Authentication failed
403	Forbidden / Insufficient permissions
404	Not Found
500	Internal Server Error

2. Organization Management

2.1 Create Organization

Creates a new organization in the SMSBAT system and automatically generates a legal contract for it.

Method: POST
URL: https://restapi.smsbat.com/api/client/organization
Headers: Authorization: Basic base64(login:password), Content-Type: application/json

Request Body Parameters:

Parameter	Type	Required	Description
`nameLocal`	`string`	Yes	Organization name in local language
`nameEn`	`string`	Yes	Organization name in English
`email`	`string`	Yes	Contact email address
`organizationType`	`int`	Yes	Organization legal type (see enum table below)
`phone`	`string`	Yes	Contact phone number (non-digit characters are automatically stripped)
`authorizedPersonDocument`	`string`	No	Document confirming authority (e.g., Charter / Articles of Association)
`authorizedPersonName`	`string`	No	Full name of authorized person
`authorizedPersonPosition`	`string`	No	Position of authorized person (e.g., Director)
`bankAccount`	`string`	No	IBAN bank account number
`bankName`	`string`	No	Bank name
`code`	`string`	No	Registration code (EDRPOU / TIN / Tax ID)
`fullLegalName`	`string`	No	Full legal entity name
`shortLegalName`	`string`	No	Short legal entity name
`isTaxPayer`	`bool`	No	VAT payer flag
`passportIssuedDate`	`datetime`	No	Passport issue date
`passportNumber`	`string`	No	Passport number
`unzr`	`string`	No	UNZR / Demographics ID number
`authToken`	`object`	No	Optional payload to auto-generate an organization authorization token
`authToken.name`	`string`	Conditional	Token name (max 255 chars)
`authToken.description`	`string`	Conditional	Token description (max 1000 chars)
`authToken.expireDate`	`datetime`	Conditional	Token expiration date (UTC, must be in the future)

Organization Type Enum (`organizationType`):

Value	Enum Name	Description
`1`	`JuridicalPerson`	Legal Entity / Company
`2`	`SoleTrader`	Sole Trader / Individual Entrepreneur (FOP)
`3`	`Individual`	Private Individual

Example Request Body:

{
  "nameLocal": "ТОВ Ромашка",
  "nameEn": "Romashka LLC",
  "email": "office@romashka.ua",
  "organizationType": 1,
  "phone": "+38 (099) 123-45-67",
  "authorizedPersonDocument": "Charter",
  "authorizedPersonName": "Ivan Petrenko",
  "authorizedPersonPosition": "Director",
  "bankAccount": "UA123456789012345678901234567",
  "bankName": "PrivatBank",
  "code": "12345678",
  "fullLegalName": "Romashka Limited Liability Company",
  "shortLegalName": "Romashka LLC",
  "isTaxPayer": true,
  "passportIssuedDate": "2020-01-01T00:00:00",
  "passportNumber": "MK123456",
  "unzr": "12345678-12345",
  "authToken": {
    "name": "Main API token",
    "description": "Primary token for system integration",
    "expireDate": "2027-08-13T00:00:00"
  }
}

Example Response (`200 OK`):

{
  "id": "5f7f9a13-f4ec-49e2-bf7f-80b60c7f55aa",
  "contractNumber": "SBT26UVBR00001",
  "nameLocal": "ТОВ Ромашка",
  "nameEn": "Romashka LLC",
  "email": "office@romashka.ua",
  "organizationType": 1,
  "phone": "380991234567",
  "authorizedPersonDocument": "Charter",
  "authorizedPersonName": "Ivan Petrenko",
  "authorizedPersonPosition": "Director",
  "bankAccount": "UA123456789012345678901234567",
  "bankName": "PrivatBank",
  "code": "12345678",
  "fullLegalName": "Romashka Limited Liability Company",
  "shortLegalName": "Romashka LLC",
  "isTaxPayer": true,
  "passportIssuedDate": "2020-01-01T00:00:00",
  "passportNumber": "MK123456",
  "unzr": "12345678-12345",
  "authToken": "9f2c1e7a4b8d3f6e2a5c8b1d4f7a3e9c2b5d8f1a"
}

Response Parameters:

Parameter	Type	Description
`id`	`guid`	Public unique GUID of the created organization
`contractNumber`	`string`	Auto-generated contract number
`phone`	`string`	Normalized digits-only phone number
`authToken`	`string`	Newly generated authorization token string (only returned if `authToken` was provided in request)

3. SMS Alpha Name Applications

3.1 Create SMS Alpha Name Application

Submits a new application to register an SMS Alpha Name for an organization.

Method: POST
URL: https://restapi.smsbat.com/api/AlphaName/sms/application
Headers: Authorization: Basic base64(username:password), Content-Type: application/json

Request Body Parameters:

Parameter	Type	Required	Description
`organizationId`	`guid`	Yes	Organization unique GUID
`alphaNameIn`	`string`	Yes	Requested Alpha Name string
`edrpou`	`string`	Yes	Tax registration ID / EDRPOU
`companyDetails`	`string`	Yes	Description of company activity
`companyWebsite`	`string`	Yes	Company website URL
`messageExample`	`string`	Yes	Sample SMS message text
`countries`	`array[string]`	Yes	Array of ISO 3166-1 alpha-2 country codes (e.g. `["UA"]`)
`callbackUrl`	`string`	No	Webhook URL for status updates

Example Request Body:

{
  "organizationId": "f33cd09e-8796-4eba-906e-6905dea0ffb9",
  "alphaNameIn": "test_alpha",
  "edrpou": "12345678",
  "companyDetails": "Retail store",
  "companyWebsite": "https://example.com",
  "messageExample": "Your verification code is 1234",
  "countries": [
    "UA"
  ],
  "callbackUrl": "https://example.com/callback"
}

Success Response (`200 OK`):

{
  "success": true
}

Error Responses:

400 Bad Request (Invalid countries format):

{
  "message": "The countries array must contain at least one value, and the values must be in ISO format."
}

400 Bad Request (Alpha Name unavailable):

{
  "message": "Alpha name unavailable."
}

404 Not Found (Organization not found):

{
  "message": "Organization by id f33cd09e-8796-4eba-906e-6905dea0ffb9 was not found."
}

4. Wallet Balance & Transaction History

4.1 Get SMS Alpha Name Wallet Information

Returns current wallet balance, currency, and paginated transaction history for a specific Alpha Name.

Method: GET
URL: https://restapi.smsbat.com/api/alphaname/wallet/info
Headers: Authorization: Basic base64(login:password)

Query Parameters:

Parameter	Type	Required	Default	Description
`externalAlphaName`	`string`	Yes	—	Target Alpha Name (e.g., `ABC123`)
`transactionTypes`	`string[]`	No	`credit`	Transaction types to filter. Repeatable parameter: `?transactionTypes=credit&transactionTypes=debit`
`page`	`int`	No	`1`	Pagination page number
`pageSize`	`int`	No	`20`	Number of items per page

Transaction Types (`transactionTypes`):

Value	Description
`credit`	Wallet balance deposit / top-up
`debit`	Wallet balance withdrawal / message usage deduction

Example Request:

GET /api/alphaname/wallet/info?externalAlphaName=ABC123&transactionTypes=credit&page=1&pageSize=20 HTTP/1.1
Host: restapi.smsbat.com
Authorization: Basic base64(login:password)

Success Response (`200 OK`):

{
  "externalAlphaName": "ABC123",
  "balance": {
    "amount": 125.50,
    "currency": "EUR",
    "lastTransactionAt": "2026-05-19T10:20:00Z"
  },
  "transactions": {
    "total": 42,
    "items": [
      {
        "occurredAt": "2026-05-19T10:20:00Z",
        "type": "credit",
        "amount": 50.00,
        "currency": "EUR"
      },
      {
        "occurredAt": "2026-05-15T08:15:00Z",
        "type": "credit",
        "amount": 100.00,
        "currency": "EUR"
      },
      {
        "occurredAt": "2026-05-12T14:30:00Z",
        "type": "debit",
        "amount": 24.50,
        "currency": "EUR"
      }
    ]
  }
}

Empty Wallet Response Example (`200 OK`):

{
  "externalAlphaName": "ABC123",
  "balance": {
    "amount": 0,
    "currency": "EUR",
    "lastTransactionAt": null
  },
  "transactions": {
    "total": 0,
    "items": []
  }
}

5. Export SMS Usage & Costs

5.1 Export SMS Statuses & Financial Reports

Downloads a ZIP archive containing a detailed CSV report of SMS dispatches, delivery counts, rates, and total spending for a given date range.

Method: GET
URL: https://restapi.smsbat.com/api/AlphaName/sms/status
Headers: Authorization: Basic base64(login:password)

Query Parameters:

Parameter	Type	Required	Description
`dateFrom`	`date`	Yes	Period start date (`YYYY-MM-DD`)
`dateTo`	`date`	Yes	Period end date (`YYYY-MM-DD`)
`alphaName`	`string`	No	Filter report by specific Alpha Name

Example Request:

GET /api/AlphaName/sms/status?dateFrom=2024-01-01&dateTo=2026-05-27 HTTP/1.1
Host: restapi.smsbat.com
Authorization: Basic base64(login:password)

Success Response:

HTTP Code: 200 OK
Content-Type: application/zip

CSV File Schema:

Column Header	Description
`AlphaName`	Sender Alpha Name
`Country`	Destination Country
`Date`	Dispatch Date
`Count`	Total messages submitted
`Delivered`	Total delivered messages count
`Failed`	Total failed / undelivered messages count
`Rate`	Applied unit rate per message
`Spent`	Total cost incurred

Error Responses:

401 Unauthorized:
```
{
  "message": "Unauthorized"
}
```

404 Not Found:

{
  "message": "Alpha name TEST was not found."
}

Search Results

SMSBAT Client & Wallet Management REST API

1. Overview & Authentication

1.1 Base URL

1.2 Authentication

1.3 Data Format

1.4 HTTP Status Codes

2. Organization Management

2.1 Create Organization

Request Body Parameters:

Organization Type Enum (organizationType):

Example Request Body:

Example Response (200 OK):

Response Parameters:

3. SMS Alpha Name Applications

3.1 Create SMS Alpha Name Application

Request Body Parameters:

Example Request Body:

Success Response (200 OK):

Error Responses:

4. Wallet Balance & Transaction History

4.1 Get SMS Alpha Name Wallet Information

Query Parameters:

Transaction Types (transactionTypes):

Example Request:

Success Response (200 OK):

Empty Wallet Response Example (200 OK):

5. Export SMS Usage & Costs

5.1 Export SMS Statuses & Financial Reports

Query Parameters:

Example Request:

Success Response:

CSV File Schema:

Error Responses:

Organization Type Enum (`organizationType`):

Example Response (`200 OK`):

Success Response (`200 OK`):

Transaction Types (`transactionTypes`):

Success Response (`200 OK`):

Empty Wallet Response Example (`200 OK`):