All SMS and Billing API resources in one place - exact endpoints, complete Postman descriptions, headers, request bodies, response examples, and ready-to-use code.
1curl --request POST \2 --url api.ubill.dev/v1/sms/send \3 --header 'key: ••••••••'
200 OK{ "statusID": 0, "message": "SMS Sent" }
GETTING STARTED
Working with the uBill API
UBill API - provides programmatic access to our resources. You will be able to integrate our service into your system and communicate with clients easily.
API examples
API implementations in different languages, provided by different sources.
Requests to protected endpoints must include your company’s secret API key. Most endpoints accept it in the key header; several legacy GET/XML endpoints use the key query parameter.
Never expose your API key
Store the key in a server-side environment variable. Never place it in frontend JavaScript, a mobile application, or a public Git repository.
Request headers
key: YOUR_API_KEY
Content-Type: application/json
02
CONVENTIONS
Formats and statuses
The API primarily returns JSON responses. The statusID field identifies the result; a successful request has the value 0. The XML endpoint returns an XML response.
0SMS sent
1Received
2Not delivered
3Awaiting status
4Error
API REFERENCE
All resources and endpoints
The information below is synchronized with the latest version of the public Postman collection.
API GROUP
SMS API
14 endpoint
SMS API / brandName Create
brandName Create
API key · Header
POSThttps://api.ubill.dev/v1/sms/brandNameCreate
Response status
statusID
Description
0
BrandName Created
10
The brandName field is empty
20
The minimum number of characters in the brandName must be 2 and the maximum number 11
30
Unauthorized markings are used in the brandName
40
brandName has already been added
50
Wait for the last added brandName to be authenticated
60
The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
Secret API key used to authenticate requests. The key can be viewed and managed in the company settings.
brandID
Unique brand identifier within the system.
numbers
Comma-separated list of mobile phone numbers. Numbers must be in international format without00 or +.
text
SMS message content. Any Unicode characters are supported.
Optional Parameters
Parameter
Description
stopList
stopList=false - disables stop list validation. The message will be sent even if the recipient number exists in the stop list.
otp
otp=true - marks the message as an OTP (one-time password / verification code). OTP messages are processed with the highest priority. ⚠️ Must be used only for authentication codes.
sendTime
Scheduled SMS delivery time. Format: Y-m-d H:i (example: 2026-02-01 23:30). The specified time must be in the future. If omitted, the message is sent immediately.
callbackUrl
Individual callback URL for this SMS request. Works only if a default callback URL is configured globally in the API application settings.
Notes
OTP messages are intended strictly for authentication flows (login, verification, password reset).
Misuse of the otp parameter may result in delivery restrictions or account limitations.
Response Status
statusID
Description
0
SMS Sent
10
brandID not found
20
Numbers not found
30
Empty message text
40
Not enough SMS
50
Valid numbers not found
60
Invalid sendTime format. Use Y-m-d H:i
90
JSON Error
99
General error
⚠️ GET Method Limitations
The API does not enforce a strict limit on the number of recipient numbers.
Actual limits are imposed by URL and HTTP header size constraints (Cloudflare, proxies, browsers).
Practical Limits
✅ Up to ~1500 numbers per request works reliably.
⚠️ Around 2000+ numbers may result in Header overflow errors.
These errors occur before the request reaches the API, at the HTTP / proxy level.
Recommendation
Use GET only for small to medium requests.
For large recipient lists, always use 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 and rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown or 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 and 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 parameters 5
keyqueryYOUR_API_KEY
brandIDquery1
numbersquery9955XXXXXXXX,9955XXXXXXXX
textquerymessage
stopListqueryfalse
Code examples
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'
Array of mobile phone numbers. Numbers must be in international format without00 or +. Example: ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS message content. Any Unicode characters are supported.
Optional Parameters (JSON Body)
Parameter
Description
stopList
false - disables stop list validation. The message will be sent even if the recipient number exists in the stop list.
otp
true - marks the message as an OTP (one-time password / verification code). OTP messages are processed with the highest priority. ⚠️ Must be used only for authentication codes.
sendTime
Scheduled SMS delivery time. Format: Y-m-d H:i (example: "2026-02-01 23:30"). Must be in the future. If omitted, the message is sent immediately.
callbackUrl
Individual callback URL for this SMS request. Works only if a default callback URL is configured globally in the API application settings.
Notes
OTP messages are intended strictly for authentication flows (login, verification, password reset).
Misuse of the otp parameter may result in delivery restrictions or account limitations.
Response Status
statusID
Description
0
SMS Sent
10
brandID not found
20
Numbers not found
30
Empty message text
40
Not enough SMS
50
Valid numbers not found
60
Invalid sendTime format. Use Y-m-d H:i
90
JSON Error
99
General error
⚠️ Limits & Notes
Max request body size: 100 MB → Requests exceeding this size will be rejected.
For large SMS batches, split requests into smaller chunks to avoid timeouts or memory issues.
Use stopList to avoid sending messages to blocked numbers.
Practical Observation from Testing:
In our tests, SMS messages were successfully sent to up to 500,000 numbers in a single request. Sending requests above this number may lead to memory, timeout, or request size issues. Actual limits may vary depending on text length, encoding, and server load.
Recommendation:
For safe and reliable operation, it is recommended to limit requests to around 100,000 numbers per batch.
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 and rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown or 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 and 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.
Request headers 2
Key
Value
Source
key
YOUR_API_KEY
Authentication
Content-Type
application/json
Header
Request body JSON
Request body
{
"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)
}
Array of mobile phone numbers. Numbers must be in international format without00 or +. Example: ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS message content. Any Unicode characters are supported.
Optional Parameters (JSON Body)
Parameter
Description
stopList
false - disables stop list validation. The message will be sent even if the recipient number exists in the stop list.
otp
true - marks the message as an OTP (one-time password / verification code). OTP messages are processed with the highest priority. ⚠️ Must be used only for authentication codes.
sendTime
Scheduled SMS delivery time. Format: Y-m-d H:i (example: "2026-02-01 23:30"). Must be in the future. If omitted, the message is sent immediately.
callbackUrl
Individual callback URL for this SMS request. Works only if a default callback URL is configured globally in the API application settings.
Notes
OTP messages are intended strictly for authentication flows (login, verification, password reset).
Misuse of the otp parameter may result in delivery restrictions or account limitations.
Response Status
statusID
Description
0
SMS Sent
10
brandID not found
20
Numbers not found
30
Empty message text
40
Not enough SMS
50
Valid numbers not found
60
Invalid sendTime format. Use Y-m-d H:i
90
JSON Error
99
General error
⚠️ Limits & Notes
Max request body size: 100 MB → Requests exceeding this size will be rejected.
For large SMS batches, split requests into smaller chunks to avoid timeouts or memory issues.
Use stopList to avoid sending messages to blocked numbers.
Practical Observation from Testing:
SMS per recipient
Maximum numbers per request
1
400,000
2
200,000
3
150,000
4
120,000
5
100,000
6
50,000
Actual limits may vary depending on text length, encoding, and server load.
Recommendation:
For safe and reliable operation, it is recommended to limit requests to the numbers listed above per batch, according to the number of concatenated SMS messages being sent.
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 and rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown or 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 and 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.
For large SMS batches, split requests to smaller chunks to avoid timeouts or memory issues.
Use stopList to avoid sending messages to blocked numbers.
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 and rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown or 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 and 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 parameters 1
keyqueryYOUR_API_KEY
Request body XML
Request body
<?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>
Code examples
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
Parameter
Type
Required
Description
date
String
No
One whole Tbilisi calendar day, for example 2026-11-02. Cannot be combined with from or to.
from
String
No
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
No
Defaults to now. A date includes its entire Tbilisi calendar day; a timestamp is an exclusive end.
limit
Integer
No
Batch size: 1–100; default 50.
cursor
String (UUIDv4)
No
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
Field
Type
Description
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 and 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
Response · JSON
{
"statusID": 404,
"message": "Cursor not found",
"result": []
}
SMS API / Incoming SMS / Get Incoming SMS by eventID
Get Incoming SMS by eventID
API key · Header
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 callback URL 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.
Field
Type
Description
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 application settings contain one shared HTTPS callback URL. The event type determines the HTTP method and payload format; not every callback is a GET request.
Use event to route notifications. Return any 2xx HTTP status after safely accepting an event.
Supported events
Event
Method
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.
No response example is available for this endpoint.
Billing API / Customers / Create Customer
Create Customer
API key · Header
POSThttps://api.ubill.dev/v1/customers/create
Creates a new customer together with its phone numbers. The customer number (id in the response) is generated automatically and is unique inside the company.
Required permission: customers.create. The request body must be JSON and the Content-Type: application/json header is mandatory.
Request body
Field
Type
Required
Description
typeID
integer
yes
Legal type of the customer, must exist in the uBill customer type list (1 = individual).
name
string, max 50
no
Customer name.
personalNo
string, max 11
no
Personal number or company identification code, alphanumeric only.
email
string
no
Must be a valid email address when sent.
birthDate
string
no
Date in YYYY-MM-DD format.
lang
string
no
One of ka, en, ru. Defaults to the default customer language configured for the company.
address
string, max 50
no
Customer address.
column1, column2
string, max 50
no
Free additional fields.
numbers
array
yes
Phone numbers of the customer, at least one is required.
numbers[] object
Field
Type
Description
number
string
Local number without the country code, 6 to 15 digits.
mobile
string
Full international number. When this key is used the country code is removed from the beginning of the number.
countryCode
string
Country code, defaults to +995.
isPrimary
0 or 1
Marks the main number. When no number is flagged, the first item of the list becomes the primary one.
smsEnabled
0 or 1
Whether the number receives SMS notifications, defaults to 1.
note
string, max 100
Free note for the number.
A single number may also be sent with the short form {"mobile": "9955XXXXXXXX", "countryCode": "+995"} instead of the numbers array. Repeated numbers are silently removed, and a number that already belongs to another customer of the same company is rejected.
Responses
HTTP
statusID
Description
201
0
Customer created, data holds the new customer.
400
400
Validation failed, the errors object names every invalid field.
500
99
The customer could not be saved, nothing is written.
{
"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"
}
}
Number already used400
Response · 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.
Required permission: customers.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY and 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.
Request body
Field
Type
Description
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
array
Replacement phone number list; omission preserves existing numbers.
typeID
integer
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
string
ka, en or ru. Cannot be cleared.
Phone numbers
Omit numbers and 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 or mobile, never both. The top-level countryCode, smsEnabled, and numberNote shortcuts require mobile.
Update behavior
If the update fails, the previous data remains unchanged.
Responses
HTTP
statusID
Description
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.
Creates a new account (service) for an existing customer. The account number (id in the response) is generated automatically according to the account numbering settings, just like an account created from the uBill web interface.
Required permission: accounts.create. The request body must be JSON and the Content-Type: application/json header is mandatory.
Request body
Field
Type
Required
Description
customerID
integer
yes
Number of the customer the account belongs to, the same id returned by the customer endpoints.
name
string, max 50
no
Account name.
birthDate
string
no
Date in YYYY-MM-DD format.
areaID
integer
no
Settlement identifier of the uBill district list.
address
string, max 50
no
Service address.
geoLocation
string, max 100
no
Coordinates in 41.732438,44.7688134 format.
column1, column2
string, max 50
no
Free additional fields.
tariffID
integer
no
Tariff number of the company.
groupID
integer
no
Group or branch number of the company.
tagsID
array of integers
no
Tag numbers of the company that are attached to the account.
numbers
array
no
Phone numbers of the account, described in the same way as for a customer. Unlike a customer, an account may be created without any number.
Module dependent fields
These fields are only read when the matching module is enabled for the company.
Field
Module
Required
Description
mac
Network
yes
MAC address of the device, unique inside the company.
onuMac
Network
no
ONU MAC address, unique inside the company.
ipRangeID
Network
yes
NAS IP range number. The first free address of that range is assigned to the account automatically and returned as ip.
stbMac
IPTV
no
STB MAC address, unique inside the company.
gpsProviderID
GPS track
yes
GPS provider number of the company.
gpsTrackIdentifier
GPS track
no
Device identifier, unique inside the company.
SMS notification
When the account added SMS notification is switched on in the company settings, the message is sent to every SMS enabled number of the new account and the SMS balance of the company is charged. If the balance is not sufficient, the account is still created and the response carries an extra warning field.
Responses
HTTP
statusID
Description
201
0
Account created, data holds the new account.
400
400
Validation failed, the errors object names every invalid field. Duplicated MAC addresses and phone numbers are reported the same way.
500
99
The account could not be saved, nothing is written.
{
"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"
}
Validation failed400
Response · 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 already used400
Response · JSON
{
"statusID": 400,
"message": "Account creation failed",
"data": null,
"errors": {
"account": [
"ეს MAC მისამართი უკვე მითითებულია სხვა ანგარიშზე"
]
}
}
Billing API / Accounts / Edit Account
Edit Account
API key · Header
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.
Required permission: accounts.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY and 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.
Request body
Field
Type
Description
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
array
Replacement phone number list; omission preserves existing numbers.
customerID
integer
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
array of integers
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
integer
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
გაუქმებული
Send {"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 and 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 or 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.
Responses
HTTP
statusID
Description
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.