Запити до захищених кінцевих точок мають містити секретний ключ API компанії. Більшість приймає його в заголовку key ; деякі застарілі GET/XML-точки використовують key параметр запиту.
Не розкривайте ключ API
Зберігайте ключ у змінній середовища сервера. Не додавайте його до клієнтського JavaScript, мобільного застосунку чи публічного Git-репозиторію.
Заголовки запиту
key: YOUR_API_KEY
Content-Type: application/json
02
ПРАВИЛА
Формати й статуси
API переважно повертає відповіді JSON. Поле statusID визначає результат; успішний запит має значення 0 . Кінцева точка XML повертає відповідь XML.
0 SMS надіслано
1 Отримано
2 Не доставлено
3 Очікування статусу
4 Помилка
ДОВІДНИК API
Усі ресурси й кінцеві точки
Наведену інформацію синхронізовано з останньою версією публічної колекції Postman.
ГРУПА API
SMS API
14 кінцева точка
SMS API / Створення імені відправника
Створення імені відправника
Ключ API · Заголовок
POSThttps://api.ubill.dev/v1/sms/brandNameCreate
Статус відповіді
statusID
Опис
0
Ім’я відправника створено
10
Поле brandName порожнє
20
brandName має містити від 2 до 11 символів
30
brandName містить недозволені символи
40
brandName уже додано
50
Дочекайтеся підтвердження останнього brandName
60
The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
Секретний ключ API для автентифікації запитів. Перегляд і керування — у налаштуваннях компанії.
brandID
Унікальний ідентифікатор бренду в системі.
numbers
Мобільні номери через кому. Мають бути в міжнародному форматі без 00 або +.
text
Текст SMS. Підтримуються всі символи Unicode.
Необов’язкові параметри
Параметр
Опис
stopList
stopList=false — вимикає перевірку стоп-списку. Повідомлення буде надіслано навіть на номер у списку.
otp
otp=true — позначає повідомлення як OTP (одноразовий пароль / код перевірки). OTP обробляються з найвищим пріоритетом. ⚠️ Слід використовувати лише для кодів автентифікації.
sendTime
Запланований час доставки SMS. Формат: Y-m-d H:i (наприклад: 2026-02-01 23:30). Зазначений час має бути в майбутньому. Якщо не вказано, надсилається негайно.
callbackUrl
Окрема URL-адреса зворотного виклику для цього запиту. Працює лише за наявності глобальної типової адреси в налаштуваннях API-застосунку.
Примітки
OTP призначені виключно для автентифікації: входу, перевірки, скидання пароля.
Неправильне використання otp параметра може призвести до обмежень доставки чи облікового запису.
API не встановлює жорсткого ліміту на кількість номерів одержувачів.
Фактичні обмеження визначаються граничним розміром URL і заголовків HTTP (Cloudflare, проксі, браузери).
Практичні обмеження
✅ До приблизно 1500 номерів у запиті працює надійно.
⚠️ Приблизно 2000 і більше номерів можуть спричинити Header overflow помилки.
Ці помилки виникають до надходження запиту до API , на рівні HTTP / проксі.
Рекомендація
Використовуйте GET лише для малих і середніх запитів.
Для великих списків завжди використовуйте POST.
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
Параметри URL 5
keyqueryYOUR_API_KEY
brandIDquery1
numbersquery9955XXXXXXXX,9955XXXXXXXX
textquerymessage
stopListqueryfalse
Приклади коду
cURL · PHP · JavaScript
cURL
curl --request GET \
--url 'https://api.ubill.dev/v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false'
Масив мобільних номерів. Мають бути в міжнародному форматі без 00 або + . Приклад: ["9955XXXXXXXX","9955XXXXXXXX"]
text
Текст SMS. Підтримуються всі символи Unicode.
Необов’язкові параметри (тіло JSON)
Параметр
Опис
stopList
false — вимикає перевірку стоп-списку. Повідомлення буде надіслано навіть на номер у списку.
otp
true — позначає повідомлення як OTP (одноразовий пароль / код перевірки). OTP обробляються з найвищим пріоритетом. ⚠️ Слід використовувати лише для кодів автентифікації.
sendTime
Запланований час доставки SMS. Формат: Y-m-d H:i (наприклад: "2026-02-01 23:30" ). Має бути в майбутньому. Якщо не вказано — надсилається негайно.
callbackUrl
Окрема URL-адреса зворотного виклику для цього запиту. Працює лише за наявності глобальної типової адреси в налаштуваннях API-застосунку.
Примітки
OTP призначені виключно для автентифікації: входу, перевірки, скидання пароля.
Неправильне використання otp параметра може призвести до обмежень доставки чи облікового запису.
Розбивайте великі пакети SMS на менші запити, щоб уникнути тайм-аутів і проблем пам’яті.
Використовуйте stopList щоб не надсилати на заблоковані номери.
Практичне спостереження під час тестування:
У наших тестах SMS успішно надсилалися на до 500 000 номерів в одному запиті . Більша кількість може спричинити проблеми пам’яті, часу очікування чи розміру запиту. Фактичні межі залежать від довжини тексту, кодування й навантаження сервера.
Рекомендація:
Для безпечної й надійної роботи рекомендовано обмежитися приблизно 100 000 номерів у пакеті .
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
Заголовки запиту 2
Ключ
Значення
Джерело
key
YOUR_API_KEY
Автентифікація
Content-Type
application/json
Заголовок
Тіло запиту JSON
Тіло запиту
{
"brandID": 1,
"numbers": [
9955XXXXXXXX,
9955XXXXXXXX
],
"text": "Message",
"stopList": false, // Enable/disable checking numbers in the stop list
"sendTime": "2026-02-01 23:01" // sendTime (optional)
}
Масив мобільних номерів. Мають бути в міжнародному форматі без 00 або + . Приклад: ["9955XXXXXXXX","9955XXXXXXXX"]
text
Текст SMS. Підтримуються всі символи Unicode.
Необов’язкові параметри (тіло JSON)
Параметр
Опис
stopList
false — вимикає перевірку стоп-списку. Повідомлення буде надіслано навіть на номер у списку.
otp
true — позначає повідомлення як OTP (одноразовий пароль / код перевірки). OTP обробляються з найвищим пріоритетом. ⚠️ Слід використовувати лише для кодів автентифікації.
sendTime
Запланований час доставки SMS. Формат: Y-m-d H:i (наприклад: "2026-02-01 23:30" ). Має бути в майбутньому. Якщо не вказано — надсилається негайно.
callbackUrl
Окрема URL-адреса зворотного виклику для цього запиту. Працює лише за наявності глобальної типової адреси в налаштуваннях API-застосунку.
Примітки
OTP призначені виключно для автентифікації: входу, перевірки, скидання пароля.
Неправильне використання otp параметра може призвести до обмежень доставки чи облікового запису.
Розбивайте великі пакети SMS на менші запити, щоб уникнути тайм-аутів і проблем пам’яті.
Використовуйте stopList щоб не надсилати на заблоковані номери.
Практичне спостереження під час тестування:
SMS на одержувача
Максимум номерів у запиті
1
400,000
2
200,000
3
150,000
4
120,000
5
100,000
6
50,000
Фактичні межі залежать від довжини тексту, кодування й навантаження сервера.
Рекомендація:
Для надійної роботи дотримуйтеся наведених меж номерів у пакеті відповідно до кількості з’єднаних SMS.
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
Розбивайте великі пакети SMS на менші запити, щоб уникнути тайм-аутів і проблем пам’яті.
Використовуйте stopList щоб не надсилати на заблоковані номери.
OTP recipient limits and partial batches
In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.
A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.
If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.
Параметри URL 1
keyqueryYOUR_API_KEY
Тіло запиту XML
Тіло запиту
<?xml version="1.0" encoding="UTF-8"?>
<request>
<brandID>1</brandID>
<numbers>9955XXXXXXXX</numbers>
<text>test</text>
<stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->
</request>
Приклади коду
cURL · PHP · JavaScript
cURL
curl --request POST \
--url 'https://api.ubill.dev/v1/sms/sendXml?key=YOUR_API_KEY' \
--data '<?xml version="1.0" encoding="UTF-8"?>
<request>
<brandID>1</brandID>
<numbers>9955XXXXXXXX</numbers>
<text>test</text>
<stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->
</request>'
Required application permission: sms.inbound. Enable Incoming SMS access in the company's API application settings and pass that application's API key in the key header. Only messages assigned to the key's company are returned. A client-supplied company ID cannot change this scope. IP restrictions and API rate limits still apply.
Without date parameters, returns the last 24 hours by provider send time. Results are in receipt order, oldest first, rather than sorted by UUID or sender timestamp. Dates in sendAt and response metadata are UTC; date-only filters use the Asia/Tbilisi calendar.
Query parameters
Параметр
Тип
Обов’язково
Опис
date
String
Ні
One whole Tbilisi calendar day, for example 2026-11-02. Cannot be combined with from або to.
from
String
Ні
Inclusive start. Accepts YYYY-MM-DD or an RFC 3339 timestamp with timezone and up to 6 fractional digits. Defaults to 24 hours before the end.
to
String
Ні
Defaults to now. A date includes its entire Tbilisi calendar day; a timestamp is an exclusive end.
limit
Integer
Ні
Batch size: 1–100; default 50.
cursor
String (UUIDv4)
Ні
Use the previous response's meta.nextCursor to retrieve later records. Unknown or other-company cursors return HTTP 404.
Date examples
GET /v1/sms/inbound
GET /v1/sms/inbound?date=2026-11-02
GET /v1/sms/inbound?from=2026-11-01&to=2026-11-02
GET /v1/sms/inbound?from=2026-11-02T00%3A00%3A00%2B04%3A00&to=2026-11-03T00%3A00%3A00%2B04%3A00
URL-encode timezone offsets, especially + as %2B. Invalid, conflicting or reversed date filters return HTTP 400.
Message fields
Поле
Тип
Опис
eventID
String (UUIDv4)
Stable UBill-generated public message ID. It is independent of the SMS provider's message ID and is also used in callbacks. Use it to deduplicate messages.
from
String
Subscriber number in local nine-digit format, for example 5XXXXXXXX.
to
String
Receiving short number.
text
String
Incoming message text. Unicode and line breaks are preserved.
noSms
Boolean
Effective NO SMS policy configured for the short number by the administrator; not the provider's flag.
sendAt
String / null
Provider send time in UTC, with microsecond precision. May be null for older imported messages.
Provider IDs and internal numeric row IDs are not exposed. Other applications of the same company with sms.inbound access see the same public message ID.
Pagination and polling
meta.count is the number of messages in this batch; meta.hasMore indicates another batch. For the next page, reuse meta.from, meta.to та meta.nextCursor so the date window remains fixed. On an empty batch, nextCursor retains the supplied cursor, or is null if no cursor was supplied.
For polling, omit dates and send the last cursor to fetch newer records within the latest 24-hour window. Persist public eventID values to handle duplicates. Use explicit dates when retrieving older history.
Errors
HTTP 400: invalid dates, limit or cursor format. HTTP 401: invalid API key or missing sms.inbound permission. HTTP 403: IP not allowed. HTTP 404: unknown or other-company cursor. HTTP 429: rate limit exceeded.
{
"statusID": 401,
"message": "Invalid API key or permission denied",
"result": []
}
Cursor not found404
Відповідь · JSON
{
"statusID": 404,
"message": "Cursor not found",
"result": []
}
SMS API / Incoming SMS / Get Incoming SMS by eventID
Get Incoming SMS by eventID
Ключ API · Заголовок
GEThttps://api.ubill.dev/v1/sms/inbound/{eventID}
Get one incoming SMS
Requires the application's sms.inbound permission and key header. Replace {eventID} with the public UUID returned by the incoming-message list or callback.
The lookup is restricted to the API key's company and has no date restriction. An invalid UUID returns HTTP 400; an unknown, provider-owned or other-company UUID returns HTTP 404. The response contains statusID and a result array with one message object.
{
"statusID": 404,
"message": "Message not found",
"result": []
}
SMS API / Incoming SMS / Incoming SMS Callback
Incoming SMS Callback
API event callback
POSThttps://example.com/callback
Incoming SMS callback
Set an HTTPS-адреса зворотного виклику for your API application and enable sms.inbound. When an incoming SMS is assigned to that company, uBill queues one delivery for each active, permitted application with a configured callback URL.
This event uses POST with a JSON body to the same callback URL used by delivery-status notifications. The event type is sms.inbound.received. Delivery-status and brand-activation events continue to use GET; a shared receiver should route by HTTP method and event type.
Authentication and fields
The application's callback key is sent both in the X-Webhook-Token header and the JSON key field. Validate it against your configured callback key. For legacy applications without a callback key, the existing API-key fallback is used.
Поле
Тип
Опис
event
String
sms.inbound.received
key
String
Callback authentication key.
eventID
String (UUIDv4)
The same stable public message ID returned by the Incoming SMS API. It is not the provider's message ID.
from
String
Subscriber's local nine-digit number.
to
String
Receiving short number.
text
String
Incoming message, including Unicode and line breaks.
noSms
Boolean
Administrator-configured short-number NO SMS policy.
sendAt
String
Provider send time in UTC with microsecond precision.
Acknowledgement and retries
After safely accepting the message, return any 2xx HTTP response. Delivery is at least once: store eventID with a unique constraint and return success for a message already accepted. A timed-out request may already have reached your server.
Network failures and non-2xx responses are retried, up to 5 HTTP attempts. Retry delays are 1 minute, 5 minutes, 30 minutes, then 2 hours; actual timing depends on worker scheduling. The message ID stays unchanged. The request timeout is 10 seconds. Redirects are not followed with the token or SMS content.
Before sending, uBill rechecks application activity, permission, company and callback URL. Removing access or disabling the app cancels pending delivery. Old messages are not automatically pushed when callbacks are first enabled; use the Incoming SMS API to retrieve history.
У налаштуваннях API-застосунку є спільна HTTPS-адреса зворотного виклику . The event type determines the HTTP method and payload format; not every callback is a GET request.
Використовуйте event to route notifications. Return any 2xx HTTP status after safely accepting an event.
Підтримувані події
Подія
Метод
Fields
sms.delivery.updated
GET query
key, event, smsID, number, statusID, date
sms.brand.activated
GET query
key, event, brandID, brandName, authorized=1, date
sms.inbound.received
POST JSON
key, event, eventID, from, to, text, noSms, sendAt
GET callbacks authenticate with the application's callback key query parameter. Incoming SMS callbacks send that key in JSON and the X-Webhook-Token header and require sms.inbound access. GET date fields use Y-m-d H:i:s; incoming SMS sendAt uses UTC RFC 3339.
Створює клієнта разом із номерами телефонів. Номер клієнта ( id in the response) is generated automatically and is unique inside the company.
Необхідний дозвіл: customers.create . Тіло запиту має бути JSON, а Content-Type: application/json заголовок обов’язковий.
Тіло запиту
Поле
Тип
Обов’язково
Опис
typeID
ціле число
так
Правовий тип клієнта має бути в переліку типів uBill ( 1 = фізична особа).
name
рядок, до 50
ні
Ім’я клієнта.
personalNo
рядок, до 11
ні
Особистий номер або код компанії, лише літери й цифри.
email
рядок
ні
Якщо надано, має бути коректною email-адресою.
birthDate
рядок
ні
Дата у YYYY-MM-DD форматі.
lang
рядок
ні
Одне зі значень ka, en, ru . Типово використовується мова клієнта з налаштувань компанії.
address
рядок, до 50
ні
Адреса клієнта.
column1, column2
рядок, до 50
ні
Довільні додаткові поля.
numbers
масив
так
Телефони клієнта, потрібен щонайменше один.
об’єкт numbers[]
Поле
Тип
Опис
number
рядок
Місцевий номер без коду країни, 6–15 цифр.
mobile
рядок
Повний міжнародний номер. За цього ключа код країни видаляється з початку номера.
countryCode
рядок
Код країни, типово +995.
isPrimary
0 або 1
Позначає основний номер. Якщо жоден не позначено, основним стає перший у списку.
smsEnabled
0 або 1
Чи отримує номер SMS-сповіщення, типово 1.
note
рядок, до 100
Довільна примітка до номера.
Один номер також можна передати скорочено {"mobile": "9955XXXXXXXX", "countryCode": "+995"} замість numbers масиву. Дублікати видаляються без сповіщення, а номер іншого клієнта тієї самої компанії відхиляється.
Відповіді
HTTP
statusID
Опис
201
0
Клієнта створено, data містить нового клієнта.
400
400
Перевірка не пройдена, errors об’єкт указує всі некоректні поля.
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"typeID": "typeID does not exist",
"birthDate": "birthDate must be a valid date in YYYY-MM-DD format",
"email": "Email is invalid",
"numbers": "Phone number is invalid"
}
}
Номер уже використовується 400
Відповідь · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"numbers": "+9955XXXXXXXX is already assigned to another customer"
}
}
Updates an existing customer in the company associated with your API key. Use the customer id returned by the create, search or get endpoints in the URL.
Необхідний дозвіл: customers.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY та Content-Type: application/json headers.
Partial update
Send a non-empty JSON object containing only fields to change. Omitted fields keep their current values. The customer ID, balance and status cannot be changed with this endpoint. Unknown fields and fields of disabled modules are rejected.
Тіло запиту
Поле
Тип
Опис
name
string/null, max 50
Name; null or empty string clears it.
birthDate
string/null
YYYY-MM-DD date; null or empty string clears it.
address
string/null, max 50
Address; null or empty string clears it.
column1, column2
string/null, max 50
Additional fields; null or empty string clears them.
numbers
масив
Replacement phone number list; omission preserves existing numbers.
typeID
ціле число
Existing legal type ID. Cannot be null.
personalNo
string/null, max 11
Alphanumeric personal or company code. Null or empty string clears it.
email
string/null, max 254
Valid email address. Null or empty string clears it.
lang
рядок
ka, en or ru. Cannot be cleared.
Phone numbers
Omit numbers та mobile to keep existing numbers. Sending either replaces the entire phone number list; include every number you want to keep. Customers require at least one number; an empty list is rejected. Sending numbers: null is invalid. Numbers already assigned to another customer in the same company are rejected; keeping a number already on this customer is allowed.
Use the same numbers[] objects as for creation: number (local digits) or mobile (full international number), countryCode (default +995), isPrimary, smsEnabled (default true), and note (maximum 100 characters). Boolean flags accept JSON booleans or 0/1. One primary number is selected; without an explicit primary flag the first number is primary. Duplicate numbers in the submitted list are collapsed. A number must have 6 to 15 digits, and country code plus number must not exceed 15 digits.
For a single number use {"mobile":"9955XXXXXXXX","countryCode":"+995","smsEnabled":true,"numberNote":"Main"}. Send either numbers або mobile, never both. The top-level countryCode, smsEnabled, and numberNote shortcuts require mobile.
Update behavior
If the update fails, the previous data remains unchanged.
Відповіді
HTTP
statusID
Опис
200
0
Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400
400
Invalid request or invalid field values. errors identifies the affected fields; data is null.
401
401
Invalid API key or missing edit permission.
403
403
The caller IP address is not allowed.
404
404
The record is missing, deleted, or belongs to another company.
415
415
The request Content-Type is not application/json.
429
429
API rate limit exceeded.
500
99
The update could not be saved. The previous data remains unchanged.
Білінг API / Облікові записи / Створення облікового запису
Створення облікового запису
Ключ API · Заголовок
POSThttps://api.ubill.dev/v1/accounts/create
Створює обліковий запис (послугу) для наявного клієнта. Номер ( id in the response) is generated automatically according to the account numbering settings, just like an account created from the uBill web interface.
Необхідний дозвіл: accounts.create . Тіло запиту має бути JSON, а Content-Type: application/json заголовок обов’язковий.
Тіло запиту
Поле
Тип
Обов’язково
Опис
customerID
ціле число
так
Номер клієнта, якому належить запис, той самий id що повертають клієнтські кінцеві точки.
name
рядок, до 50
ні
Назва облікового запису.
birthDate
рядок
ні
Дата у YYYY-MM-DD форматі.
areaID
ціле число
ні
Ідентифікатор населеного пункту в переліку районів uBill.
address
рядок, до 50
ні
Адреса надання послуги.
geoLocation
рядок, до 100
ні
Координати у 41.732438,44.7688134 форматі.
column1, column2
рядок, до 50
ні
Довільні додаткові поля.
tariffID
ціле число
ні
Номер тарифу компанії.
groupID
ціле число
ні
Номер групи чи філії компанії.
tagsID
масив цілих чисел
ні
Номери міток компанії, прикріплених до запису.
numbers
масив
ні
Телефони запису описуються так само, як для клієнта. На відміну від клієнта, запис можна створити без номера.
Поля залежно від модуля
Поля зчитуються лише за активного відповідного модуля компанії.
Поле
Модуль
Обов’язково
Опис
mac
Мережа
так
MAC-адреса пристрою, унікальна в межах компанії.
onuMac
Мережа
ні
MAC-адреса ONU, унікальна в межах компанії.
ipRangeID
Мережа
так
Номер діапазону IP NAS. Перша вільна адреса автоматично призначається запису й повертається як ip.
stbMac
IPTV
ні
MAC-адреса STB, унікальна в межах компанії.
gpsProviderID
GPS track
так
Номер GPS-провайдера компанії.
gpsTrackIdentifier
GPS track
ні
Ідентифікатор пристрою, унікальний у межах компанії.
SMS-сповіщення
Якщо ввімкнено SMS про створення запису, повідомлення надсилається на всі його номери з активними SMS, зі списанням балансу компанії. За недостатнього балансу запис усе одно створюється, а відповідь містить додаткове warning поле.
Відповіді
HTTP
statusID
Опис
201
0
Обліковий запис створено, data містить новий обліковий запис.
400
400
Перевірка не пройдена, errors об’єкт указує некоректні поля. Дублікати MAC-адрес і телефонів повідомляються так само.
{
"statusID": 0,
"message": "Account created",
"data": {
"id": 100002,
"customerID": 100001,
"name": "მეორე ბინა",
"mobile": "9955XXXXXXXX",
"numbers": [
{
"mobile": "9955XXXXXXXX",
"countryCode": "+995",
"number": "5XXXXXXXX",
"isPrimary": 1,
"smsEnabled": 1,
"note": null
}
],
"personalNo": "XXXXXXXXXXX",
"birthDate": null,
"areaID": null,
"area": "არ არის მითითებული",
"address": "",
"geoLocation": null,
"column1": "",
"column2": "",
"groupID": null,
"tagsID": [],
"tariffID": null,
"balance": "0.00",
"statusID": 1,
"createdAt": "2026-08-26 13:20:11"
},
"warning": "account was created, but the notification sms was not sent - not enough messages on the balance"
}
Перевірку не пройдено 400
Відповідь · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"customerID": "Customer not found",
"geoLocation": "geoLocation must look like 41.732438,44.7688134",
"tariffID": "tariffID does not exist",
"mac": "mac is required",
"ipRangeID": "ipRangeID is required"
}
}
MAC уже використовується 400
Відповідь · JSON
{
"statusID": 400,
"message": "Account creation failed",
"data": null,
"errors": {
"account": [
"ეს MAC მისამართი უკვე მითითებულია სხვა ანგარიშზე"
]
}
}
Billing API / Accounts / Edit Account
Edit Account
Ключ API · Заголовок
POSThttps://api.ubill.dev/v1/accounts/edit/100001
Updates an existing account in the company associated with your API key. Use the account id returned by the create, search or get endpoints in the URL.
Необхідний дозвіл: accounts.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY та Content-Type: application/json headers.
Partial update
Send a non-empty JSON object containing only fields to change. Omitted fields keep their current values. The account ID and balance cannot be changed with this endpoint. Unknown fields and fields of disabled modules are rejected.
Тіло запиту
Поле
Тип
Опис
name
string/null, max 50
Name; null or empty string clears it.
birthDate
string/null
YYYY-MM-DD date; null or empty string clears it.
address
string/null, max 50
Address; null or empty string clears it.
column1, column2
string/null, max 50
Additional fields; null or empty string clears them.
numbers
масив
Replacement phone number list; omission preserves existing numbers.
customerID
ціле число
Customer id returned by the customer endpoints for your company. Cannot be null.
areaID
integer/null
Settlement ID; null removes the settlement.
geoLocation
string/null
Latitude,longitude with latitude between -90 and 90 and longitude between -180 and 180; null or empty string clears it.
tariffID, groupID
integer/null
Public tariff/group IDs in the same company. Null removes the link.
tagsID
масив цілих чисел
Full replacement list of public tag IDs. [] removes all tags; omission preserves them.
mac, onuMac
string/null, max 45
Available only with the Network module. Values must be unique within the company; null or empty string clears them.
ipRangeID
integer/null
Network module only. Public NAS range ID. A changed range assigns the first free IP; if exhausted, the request fails. Null removes both the range and IP. An unchanged range preserves the IP.
stbMac
string/null, max 45
IPTV module only. Must be unique within the company.
gpsProviderID
integer/null
GPS module only. Public GPS provider ID; null clears it.
gpsTrackIdentifier
string/null, max 255
GPS module only. Unique device identifier; null or empty string clears it.
statusID
ціле число
Account status: 1 = Active (აქტიური), 2 = Passive (პასიური), 3 = Suspended (შეჩერებული), 4 = Cancelled (გაუქმებული). Omission keeps the current status; null, strings and unknown IDs are rejected.
Account statuses / ანგარიშის სტატუსები
statusID
Meaning
ქართული მნიშვნელობა
1
Active
აქტიური
2
Passive
პასიური
3
Suspended
შეჩერებული
4
Cancelled
გაუქმებული
Надіслати {"statusID":2} to make an account passive. The updated account status is returned in data.statusID, with its catalog label in data.statusName. The top-level statusID: 0 describes API success, not the account status.
Status 4 clears the assigned IP. The account, its ID and phone numbers are preserved. Balance, credit, tariff and billing dates remain unchanged by a status change.
Phone numbers
Omit numbers та mobile to keep existing numbers. Sending either replaces the entire phone number list; include every number you want to keep. Accounts may have no numbers; send numbers: [] to clear the list. Sending numbers: null is invalid. Numbers already assigned to another account in the same company are rejected; keeping a number already on this account is allowed.
Use the same numbers[] objects as for creation: number (local digits) or mobile (full international number), countryCode (default +995), isPrimary, smsEnabled (default true), and note (maximum 100 characters). Boolean flags accept JSON booleans or 0/1. One primary number is selected; without an explicit primary flag the first number is primary. Duplicate numbers in the submitted list are collapsed. A number must have 6 to 15 digits, and country code plus number must not exceed 15 digits.
For a single number use {"mobile":"9955XXXXXXXX","countryCode":"+995","smsEnabled":true,"numberNote":"Main"}. Send either numbers або mobile, never both. The top-level countryCode, smsEnabled, and numberNote shortcuts require mobile.
Update behavior
If the update fails, the previous data remains unchanged. Editing an account does not send the account creation SMS notification.
Відповіді
HTTP
statusID
Опис
200
0
Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400
400
Invalid request or invalid field values. errors identifies the affected fields; data is null.
401
401
Invalid API key or missing edit permission.
403
403
The caller IP address is not allowed.
404
404
The record is missing, deleted, or belongs to another company.
415
415
The request Content-Type is not application/json.
429
429
API rate limit exceeded.
500
99
The update could not be saved. The previous data remains unchanged.