uBill DevelopersREST API · v1 Production

Complete API Documentation

All SMS and Billing API resources in one place - exact endpoints, complete Postman descriptions, headers, request bodies, response examples, and ready-to-use code.

29 endpoint API key auth JSON / XML
POST /v1/sms/send
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.

Base URLhttps://api.ubill.dev
Versionv1
ProtocolHTTPS
EncodingUTF-8
01
SECURITY

Authentication

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
POST https://api.ubill.dev /v1/sms/brandNameCreate

Response status

statusIDDescription
0BrandName Created
10The brandName field is empty
20The minimum number of characters in the brandName must be 2 and the maximum number 11
30Unauthorized markings are used in the brandName
40brandName has already been added
50Wait for the last added brandName to be authenticated
60The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
61The description must not exceed 500 characters
90Json Error
99General error

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "brandName" : "test"
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/brandNameCreate' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brandName" : "test"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/brandNameCreate',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "brandName" : "test"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/brandNameCreate',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandName\" : \"test\"\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
brandName Create Example
Response · JSON
{
    "statusID": 0,
    "brandID": 1,
    "message": "BrandName Created"
}
SMS API / brandName Delete

brandName Delete

API key · Header
POST https://api.ubill.dev /v1/sms/brandNameDelete

Response status

statusIDDescription
0BrandName Deleted
10BrandName not found
90Json Error
99General error

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "brandID": 2
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/brandNameDelete' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brandID": 2
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/brandNameDelete',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "brandID": 2
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/brandNameDelete',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandID\": 2\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
brandName Delete Example
Response · JSON
{
    "statusID": 0,
    "brandID": "2",
    "message": "BrandName Deleted"
}
SMS API / Get All BrandNames

Get All BrandNames

API key · Header
GET https://api.ubill.dev /v1/sms/brandNames

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/brandNames' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/brandNames',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/brandNames',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Get All BrandNames Example
Response · JSON
{
    "statusID": 0,
    "data": [
        {
            "id": "1",
            "name": "test",
            "authorized": "1",
            "createdAt": "2020-11-14 20:42:44"
        },
        {
            "id": "2",
            "name": "test2",
            "authorized": "2",
            "createdAt": "2021-03-27 00:22:38"
        }
    ]
}
SMS API / Send SMS

Send SMS

API key · Query
GET https://api.ubill.dev /v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false

Required Parameters

Parameter Description
key 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 without 00 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'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET'
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false',
  {
  method: 'GET'
  }
);

const data = await response.json();
console.log(data);

Response examples

3 example
Send SMS Example
Response · JSON
{
    "statusID": 0,
    "smsID": "117345",
    "message": "SMS Sent"
}
OTP partial success 200
Response · JSON
{
  "statusID": 0,
  "smsID": 123,
  "message": "SMS partially sent",
  "acceptedCount": 1,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
OTP all recipients restricted 200
Response · JSON
{
  "statusID": 47,
  "smsID": null,
  "message": "OTP recipient protection limit exceeded",
  "acceptedCount": 0,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
SMS API / Send SMS

Send SMS

API key · Header
POST https://api.ubill.dev /v1/sms/send

Headers

Key Value
key Your secret API key
Content-Type application/json

Required Parameters (JSON Body)

Parameter Description
brandID Unique brand identifier within the system.
numbers Array of mobile phone numbers. Numbers must be in international format without 00 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.

  • Cloudflare proxied timeout: 100 seconds → Requests taking longer will return 524 Timeout.

  • 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

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

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)
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/send' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "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)
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'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)
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/send',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandID\": 1,\n    \"numbers\": [\n        9955XXXXXXXX,\n        9955XXXXXXXX\n    ],\n    \"text\": \"Message\",\n    \"stopList\": false, // Enable/disable checking numbers in the stop list\n    \"sendTime\": \"2026-02-01 23:01\" // sendTime (optional)\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

3 example
Send SMS Example
Response · JSON
{
    "statusID": 0,
    "smsID": 111,
    "message": "SMS Sended"
}
OTP partial success 200
Response · JSON
{
  "statusID": 0,
  "smsID": 123,
  "message": "SMS partially sent",
  "acceptedCount": 1,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
OTP all recipients restricted 200
Response · JSON
{
  "statusID": 47,
  "smsID": null,
  "message": "OTP recipient protection limit exceeded",
  "acceptedCount": 0,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
SMS API / Send SMS - Multiple Text

Send SMS - Multiple Text

API key · Header
POST https://api.ubill.dev /v1/sms/send

Headers

Key Value
key Your secret API key
Content-Type application/json

Required Parameters (JSON Body)

Parameter Description
brandID Unique brand identifier within the system.
numbers Array of mobile phone numbers. Numbers must be in international format without 00 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.

  • Cloudflare proxied timeout: 100 seconds → Requests taking longer will return 524 Timeout.

  • 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.

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "brandID": 1,
    "numbers": [
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, Nicholas"
        },
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, George"
        }
    ],
    "stopList": false, // Enable/disable checking numbers in the stop list
    "sendTime": "2026-02-01 23:01" // sendTime (optional)
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/send' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brandID": 1,
    "numbers": [
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, Nicholas"
        },
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, George"
        }
    ],
    "stopList": false, // Enable/disable checking numbers in the stop list
    "sendTime": "2026-02-01 23:01" // sendTime (optional)
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "brandID": 1,
    "numbers": [
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, Nicholas"
        },
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, George"
        }
    ],
    "stopList": false, // Enable/disable checking numbers in the stop list
    "sendTime": "2026-02-01 23:01" // sendTime (optional)
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/send',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandID\": 1,\n    \"numbers\": [\n        {\n            \"number\": 9955XXXXXXXX,\n            \"text\": \"Hello, Nicholas\"\n        },\n        {\n            \"number\": 9955XXXXXXXX,\n            \"text\": \"Hello, George\"\n        }\n    ],\n    \"stopList\": false, // Enable/disable checking numbers in the stop list\n    \"sendTime\": \"2026-02-01 23:01\" // sendTime (optional)\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

3 example
Send SMS - Multiple Text Example
Response · JSON
{
    "statusID": 0,
    "smsID": 111,
    "message": "SMS Sended"
}
OTP partial success 200
Response · JSON
{
  "statusID": 0,
  "smsID": 123,
  "message": "SMS partially sent",
  "acceptedCount": 1,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
OTP all recipients restricted 200
Response · JSON
{
  "statusID": 47,
  "smsID": null,
  "message": "OTP recipient protection limit exceeded",
  "acceptedCount": 0,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
SMS API / Send SMS XML

Send SMS XML

API key · Query
POST https://api.ubill.dev /v1/sms/sendXml?key=YOUR_API_KEY

Response status

statusIDDescription
0SMS Sended
10brandID not found
20Numbers not found
30Empty message text
40Not enough SMS
50Valid numbers not found
90Json Error
99General error

⚠️ Limits & Notes

  • Max request body size: 100 MB → Requests exceeding this size will be rejected.

  • Cloudflare proxied timeout: 100 seconds → Requests taking longer will return 524 Timeout.

  • 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>'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/sendXml?key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'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>
BODY
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/sendXml?key=YOUR_API_KEY',
  {
  method: 'POST',
  body: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<request>\n    <brandID>1</brandID>\n    <numbers>9955XXXXXXXX</numbers>\n    <text>test</text>\n    <stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->\n</request>"
  }
);

const data = await response.json();
console.log(data);

Response examples

3 example
Send SMS XML Example
Response · XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <statusID>0</statusID>
    <smsID>11574</smsID>
    <message>SMS Sent</message>
</response>
OTP partial success 200
Response · XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <statusID>0</statusID>
    <smsID>123</smsID>
    <message>SMS partially sent</message>
    <acceptedCount>1</acceptedCount>
    <rejectedCount>1</rejectedCount>
    <rejectedNumbers>
        <recipient>
            <index>0</index>
            <number>599000001</number>
            <statusID>47</statusID>
            <reason>otpCooldown</reason>
            <retryAfter>30</retryAfter>
        </recipient>
    </rejectedNumbers>
</response>
OTP all recipients restricted 200
Response · XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <statusID>47</statusID>
    <smsID>null</smsID>
    <message>OTP recipient protection limit exceeded</message>
    <acceptedCount>0</acceptedCount>
    <rejectedCount>1</rejectedCount>
    <rejectedNumbers>
        <recipient>
            <index>0</index>
            <number>599000001</number>
            <statusID>47</statusID>
            <reason>otpCooldown</reason>
            <retryAfter>30</retryAfter>
        </recipient>
    </rejectedNumbers>
</response>
SMS API / Delivery Report

Delivery Report

API key · Header
GET https://api.ubill.dev /v1/sms/report/{smsID}

Statuses

statusID Description
0 Sent
1 Received
2 Not delivered
3 Awaiting status
4 Error

URL parameters 1

smsIDpath{smsID}

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/report/{smsID}' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/report/{smsID}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/report/{smsID}',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Delivery Report Example
Response · JSON
{
    "statusID": 0,
    "result": [
        {
            "number": "9955XXXXXXXX",
            "statusID": "0"
        },
        {
            "number": "9955XXXXXXXX",
            "statusID": "0"
        }
    ]
}
SMS API / Get SMS Balance

Get SMS Balance

API key · Query
GET https://api.ubill.dev /v1/sms/balance?key=YOUR_API_KEY

URL parameters 1

keyqueryYOUR_API_KEY

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/balance?key=YOUR_API_KEY'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/balance?key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET'
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/balance?key=YOUR_API_KEY',
  {
  method: 'GET'
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Get SMS Balance Example
Response · JSON
{
    "statusID": 0,
    "sms": 5000
}
RESOURCE

Incoming SMS

3 endpoint

SMS API / Incoming SMS / Get Incoming SMS

Get Incoming SMS

API key · Header
GET https://api.ubill.dev /v1/sms/inbound

Incoming SMS — receive messages through the API

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

ParameterTypeRequiredDescription
dateStringNoOne whole Tbilisi calendar day, for example 2026-11-02. Cannot be combined with from or to.
fromStringNoInclusive 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.
toStringNoDefaults to now. A date includes its entire Tbilisi calendar day; a timestamp is an exclusive end.
limitIntegerNoBatch size: 1–100; default 50.
cursorString (UUIDv4)NoUse 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

FieldTypeDescription
eventIDString (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.
fromStringSubscriber number in local nine-digit format, for example 5XXXXXXXX.
toStringReceiving short number.
textStringIncoming message text. Unicode and line breaks are preserved.
noSmsBooleanEffective NO SMS policy configured for the short number by the administrator; not the provider's flag.
sendAtString / nullProvider 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.

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Acceptapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/inbound' \
  --header 'key: YOUR_API_KEY' \
  --header 'Accept: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/inbound',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Accept: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/inbound',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Accept': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

5 example
Last 24 hours 200
Response · JSON
{
  "statusID": 0,
  "meta": {
    "from": "2026-11-01T09:00:00.000000Z",
    "to": "2026-11-02T09:00:00.000000Z",
    "limit": 50,
    "count": 1,
    "hasMore": false,
    "nextCursor": "29a24670-e631-4bf3-b593-ea35df838115"
  },
  "result": [
    {
      "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
      "from": "5XXXXXXXX",
      "to": "90566",
      "text": "Example incoming SMS",
      "noSms": false,
      "sendAt": "2026-11-02T08:30:00.396288Z"
    }
  ]
}
No messages 200
Response · JSON
{
  "statusID": 0,
  "meta": {
    "from": "2026-11-01T09:00:00.000000Z",
    "to": "2026-11-02T09:00:00.000000Z",
    "limit": 50,
    "count": 0,
    "hasMore": false,
    "nextCursor": null
  },
  "result": []
}
Invalid date 400
Response · JSON
{
  "statusID": 400,
  "message": "Invalid date",
  "result": []
}
Permission denied 401
Response · JSON
{
  "statusID": 401,
  "message": "Invalid API key or permission denied",
  "result": []
}
Cursor not found 404
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
GET https://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.

URL parameters 1

eventIDpath{eventID}

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Acceptapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/inbound/{eventID}' \
  --header 'key: YOUR_API_KEY' \
  --header 'Accept: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/inbound/{eventID}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Accept: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/inbound/{eventID}',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Accept': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

3 example
Incoming message 200
Response · JSON
{
  "statusID": 0,
  "result": [
    {
      "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
      "from": "5XXXXXXXX",
      "to": "90566",
      "text": "Example incoming SMS",
      "noSms": false,
      "sendAt": "2026-11-02T08:30:00.396288Z"
    }
  ]
}
Invalid message ID 400
Response · JSON
{
  "statusID": 400,
  "message": "Invalid ID",
  "result": []
}
Message not found 404
Response · JSON
{
  "statusID": 404,
  "message": "Message not found",
  "result": []
}
SMS API / Incoming SMS / Incoming SMS Callback

Incoming SMS Callback

API event callback
POST https://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.

FieldTypeDescription
eventStringsms.inbound.received
keyStringCallback authentication key.
eventIDString (UUIDv4)The same stable public message ID returned by the Incoming SMS API. It is not the provider's message ID.
fromStringSubscriber's local nine-digit number.
toStringReceiving short number.
textStringIncoming message, including Unicode and line breaks.
noSmsBooleanAdministrator-configured short-number NO SMS policy.
sendAtStringProvider 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.

Request headers 2

KeyValueSource
Content-Typeapplication/jsonHeader
X-Webhook-TokenYOUR_CALLBACK_KEYHeader

Request body JSON

Request body
{
  "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
  "from": "5XXXXXXXX",
  "to": "90566",
  "text": "Example incoming SMS",
  "noSms": false,
  "sendAt": "2026-11-02T08:30:00.396288Z",
  "event": "sms.inbound.received",
  "key": "YOUR_CALLBACK_KEY"
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://example.com/callback' \
  --header 'Content-Type: application/json' \
  --header 'X-Webhook-Token: YOUR_CALLBACK_KEY' \
  --data '{
  "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
  "from": "5XXXXXXXX",
  "to": "90566",
  "text": "Example incoming SMS",
  "noSms": false,
  "sendAt": "2026-11-02T08:30:00.396288Z",
  "event": "sms.inbound.received",
  "key": "YOUR_CALLBACK_KEY"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://example.com/callback',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
  "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
  "from": "5XXXXXXXX",
  "to": "90566",
  "text": "Example incoming SMS",
  "noSms": false,
  "sendAt": "2026-11-02T08:30:00.396288Z",
  "event": "sms.inbound.received",
  "key": "YOUR_CALLBACK_KEY"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Webhook-Token: YOUR_CALLBACK_KEY'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://example.com/callback',
  {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Token': 'YOUR_CALLBACK_KEY'
  },
  body: "{\n  \"eventID\": \"29a24670-e631-4bf3-b593-ea35df838115\",\n  \"from\": \"5XXXXXXXX\",\n  \"to\": \"90566\",\n  \"text\": \"Example incoming SMS\",\n  \"noSms\": false,\n  \"sendAt\": \"2026-11-02T08:30:00.396288Z\",\n  \"event\": \"sms.inbound.received\",\n  \"key\": \"YOUR_CALLBACK_KEY\"\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Accepted by your endpoint (example) 200
Response · JSON
{
  "success": true
}
SMS API / API Event Callbacks

API Event Callbacks

API key · Query
GET https://example.com/callback?key=YourCallbackKey&event=sms.brand.activated&brandID=12&brandName=MyBrand&authorized=1&date=2026-08-10 15:30:00

API Event Callbacks

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

EventMethodFields
sms.delivery.updatedGET querykey, event, smsID, number, statusID, date
sms.brand.activatedGET querykey, event, brandID, brandName, authorized=1, date
sms.inbound.receivedPOST JSONkey, 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.

SMS brand activation example

https://example.com/callback?key=YourCallbackKey&event=sms.brand.activated&brandID=12&brandName=MyBrand&authorized=1&date=2026-08-10%2015:30:00

See Incoming SMS → Incoming SMS Callback for the JSON body, authentication, retries and deduplication rules.

URL parameters 6

keyqueryYourCallbackKey
eventquerysms.brand.activated
brandIDquery12
brandNamequeryMyBrand
authorizedquery1
datequery2026-08-10 15:30:00

Code examples

cURL · PHP · JavaScript

Response examples

0 example
No response example is available for this endpoint.
SMS API / SMS Delivery Callback

SMS Delivery Callback

API key · Query
GET https://example.com/callback?key=YourCallbackKey&event=sms.delivery.updated&smsID=12345678&number=9955XXXXXXXX&statusID=1&date=2026-02-01 12:02:02

Automatic Message Status (Callback)

The SMS API allows you to automatically receive the status of sent messages on your server via the Callback mechanism.

When a message status changes (Sent, Received, Not Delivered, etc.), the system will send a GET request to your specified HTTPS URL.

Callback URL requirements:

  • Must start with https://

  • Method: GET

  • Set in company API settings

Parameters

Parameter Description
key Callback validation key for your server
smsID Unique identifier of the message
number Recipient's mobile number (international format)
statusID Current status code of the message
date Status update timestamp (Y-m-d H:i:s)

Status Codes

statusID Description
0 Sent
1 Received
2 Not Delivered
3 Awaiting Status
4 Error

Example Callback Handling (PHP)

$key    = $_GET['key'] ?? null;
$smsID    = $_GET['smsID'] ?? null;
$number   = $_GET['number'] ?? null;
$statusID = $_GET['statusID'] ?? null;
$date     = $_GET['date'] ?? null;

// Validation: ensure the key matches your callback key
if ($key !== 'YourCallbackKey') {
    http_response_code(403);
    echo 'Forbidden';
    exit;
}

// Process the received status in your system
http_response_code(200);
echo 'OK';
?>

URL parameters 6

keyqueryYourCallbackKey
eventquerysms.delivery.updated
smsIDquery12345678
numberquery9955XXXXXXXX
statusIDquery1
datequery2026-02-01 12:02:02

Code examples

cURL · PHP · JavaScript

Response examples

0 example
No response example is available for this endpoint.
API GROUP

Billing API

15 endpoint

RESOURCE

Customers

6 endpoint

Billing API / Customers / Get All Customers

Get All Customers

API key · Header
GET https://api.ubill.dev /v1/customers

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

0 example
No response example is available for this endpoint.
Billing API / Customers / Create Customer

Create Customer

API key · Header
POST https://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

FieldTypeRequiredDescription
typeIDintegeryesLegal type of the customer, must exist in the uBill customer type list (1 = individual).
namestring, max 50noCustomer name.
personalNostring, max 11noPersonal number or company identification code, alphanumeric only.
emailstringnoMust be a valid email address when sent.
birthDatestringnoDate in YYYY-MM-DD format.
langstringnoOne of ka, en, ru. Defaults to the default customer language configured for the company.
addressstring, max 50noCustomer address.
column1, column2string, max 50noFree additional fields.
numbersarrayyesPhone numbers of the customer, at least one is required.

numbers[] object

FieldTypeDescription
numberstringLocal number without the country code, 6 to 15 digits.
mobilestringFull international number. When this key is used the country code is removed from the beginning of the number.
countryCodestringCountry code, defaults to +995.
isPrimary0 or 1Marks the main number. When no number is flagged, the first item of the list becomes the primary one.
smsEnabled0 or 1Whether the number receives SMS notifications, defaults to 1.
notestring, max 100Free 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

HTTPstatusIDDescription
2010Customer created, data holds the new customer.
400400Validation failed, the errors object names every invalid field.
50099The customer could not be saved, nothing is written.

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "typeID": 1,
    "name": "გიორგი მაისურაძე",
    "personalNo": "XXXXXXXXXXX",
    "email": "[email protected]",
    "birthDate": "1990-05-17",
    "lang": "ka",
    "address": "ვაჟა-ფშაველას 1",
    "column1": "",
    "column2": "",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1,
            "note": "პირადი"
        },
        {
            "mobile": "9955XXXXXXXX",
            "smsEnabled": 0,
            "note": "ბიოს"
        }
    ]
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/customers/create' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "typeID": 1,
    "name": "გიორგი მაისურაძე",
    "personalNo": "XXXXXXXXXXX",
    "email": "[email protected]",
    "birthDate": "1990-05-17",
    "lang": "ka",
    "address": "ვაჟა-ფშაველას 1",
    "column1": "",
    "column2": "",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1,
            "note": "პირადი"
        },
        {
            "mobile": "9955XXXXXXXX",
            "smsEnabled": 0,
            "note": "ბიოს"
        }
    ]
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "typeID": 1,
    "name": "გიორგი მაისურაძე",
    "personalNo": "XXXXXXXXXXX",
    "email": "[email protected]",
    "birthDate": "1990-05-17",
    "lang": "ka",
    "address": "ვაჟა-ფშაველას 1",
    "column1": "",
    "column2": "",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1,
            "note": "პირადი"
        },
        {
            "mobile": "9955XXXXXXXX",
            "smsEnabled": 0,
            "note": "ბიოს"
        }
    ]
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/create',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"typeID\": 1,\n    \"name\": \"გიორგი მაისურაძე\",\n    \"personalNo\": \"XXXXXXXXXXX\",\n    \"email\": \"[email protected]\",\n    \"birthDate\": \"1990-05-17\",\n    \"lang\": \"ka\",\n    \"address\": \"ვაჟა-ფშაველას 1\",\n    \"column1\": \"\",\n    \"column2\": \"\",\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": 1,\n            \"smsEnabled\": 1,\n            \"note\": \"პირადი\"\n        },\n        {\n            \"mobile\": \"9955XXXXXXXX\",\n            \"smsEnabled\": 0,\n            \"note\": \"ბიოს\"\n        }\n    ]\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

3 example
Customer created 201
Response · JSON
{
    "statusID": 0,
    "message": "Customer created",
    "data": {
        "id": 100001,
        "typeID": 1,
        "name": "გიორგი მაისურაძე",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "mobile": "9955XXXXXXXX",
                "countryCode": "+995",
                "number": "5XXXXXXXX",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": "პირადი"
            },
            {
                "mobile": "9955XXXXXXXX",
                "countryCode": "+995",
                "number": "5XXXXXXXX",
                "isPrimary": 0,
                "smsEnabled": 0,
                "note": "ბიოს"
            }
        ],
        "personalNo": "XXXXXXXXXXX",
        "email": "[email protected]",
        "birthDate": "1990-05-17",
        "address": "ვაჟა-ფშაველას 1",
        "lang": "ka",
        "column1": "",
        "column2": "",
        "createdAt": "2026-08-26 13:19:02"
    }
}
Validation failed 400
Response · JSON
{
    "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 used 400
Response · JSON
{
    "statusID": 400,
    "message": "Validation failed",
    "data": null,
    "errors": {
        "numbers": "+9955XXXXXXXX is already assigned to another customer"
    }
}
Billing API / Customers / Edit Customer

Edit Customer

API key · Header
POST https://api.ubill.dev /v1/customers/edit/100001

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

FieldTypeDescription
namestring/null, max 50Name; null or empty string clears it.
birthDatestring/nullYYYY-MM-DD date; null or empty string clears it.
addressstring/null, max 50Address; null or empty string clears it.
column1, column2string/null, max 50Additional fields; null or empty string clears them.
numbersarrayReplacement phone number list; omission preserves existing numbers.
typeIDintegerExisting legal type ID. Cannot be null.
personalNostring/null, max 11Alphanumeric personal or company code. Null or empty string clears it.
emailstring/null, max 254Valid email address. Null or empty string clears it.
langstringka, 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

HTTPstatusIDDescription
2000Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400400Invalid request or invalid field values. errors identifies the affected fields; data is null.
401401Invalid API key or missing edit permission.
403403The caller IP address is not allowed.
404404The record is missing, deleted, or belongs to another company.
415415The request Content-Type is not application/json.
429429API rate limit exceeded.
50099The update could not be saved. The previous data remains unchanged.

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "name": "Updated Customer",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "email": "[email protected]"
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/customers/edit/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Customer",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "email": "[email protected]"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/edit/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "name": "Updated Customer",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "email": "[email protected]"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/edit/100001',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"name\": \"Updated Customer\",\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": true,\n            \"smsEnabled\": true,\n            \"note\": \"Main number\"\n        },\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"smsEnabled\": false,\n            \"note\": \"Additional number\"\n        }\n    ],\n    \"email\": \"[email protected]\"\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

4 example
Updated 200
Response · JSON
{
    "statusID": 0,
    "message": "Customer updated",
    "data": {
        "id": 100001,
        "name": "Updated Customer",
        "birthDate": null,
        "address": "Tbilisi",
        "column1": null,
        "column2": null,
        "createdAt": "2026-10-01 10:00:00",
        "updatedAt": "2026-10-27 12:00:00",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": "Main number",
                "mobile": "9955XXXXXXXX"
            },
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "smsEnabled": 0,
                "note": "Additional number",
                "mobile": "9955XXXXXXXX",
                "isPrimary": 0
            }
        ],
        "typeID": 1,
        "personalNo": "XXXXXXXXXXX",
        "email": "[email protected]",
        "lang": "ka"
    }
}
Validation failed 400
Response · JSON
{
    "statusID": 400,
    "message": "Validation failed",
    "data": null,
    "errors": {
        "numbers": "Phone number is invalid"
    }
}
Not found 404
Response · JSON
{
    "statusID": 404,
    "message": "Customer not found",
    "data": null
}
Storage failure 500
Response · JSON
{
    "statusID": 99,
    "message": "Customer update failed",
    "data": null
}
Billing API / Customers / Get Customer

Get Customer

API key · Header
GET https://api.ubill.dev /v1/customers/100001

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

0 example
No response example is available for this endpoint.
Billing API / Customers / Customer Search

Customer Search

API key · Header
GET https://api.ubill.dev /v1/customers/search?type=mobile&value=9955XXXXXXXX

URL parameters 2

typequerymobile
valuequery9955XXXXXXXX

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers/search?type=mobile&value=9955XXXXXXXX' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/search?type=mobile&value=9955XXXXXXXX',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/search?type=mobile&value=9955XXXXXXXX',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

0 example
No response example is available for this endpoint.
Billing API / Customers / Customer Accounts

Customer Accounts

API key · Header
GET https://api.ubill.dev /v1/customers/accounts/100001

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers/accounts/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/accounts/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/accounts/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Customer Accounts Example
Response · JSON
{
    "statusID": 0,
    "message": "Success",
    "draw": 0,
    "recordsTotal": 3,
    "recordsFiltered": 3,
    "data": [
        {
            "id": "170115",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "ბათუმი - ბათუმი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": null,
            "tariffName": null,
            "tariffPrice": null,
            "balance": "0.00",
            "statusID": "1",
            "statusName": "აქტიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-12-02 11:41:37"
        },
        {
            "id": "170114",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "ბათუმი - ბათუმი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-2.00",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-11-20 23:56:52"
        },
        {
            "id": "100001",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "2",
            "area": "თბილისი - თბილისი",
            "address": "Example Address",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-9.71",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": "2022-07-13",
            "creditDate": null,
            "mac": "Cc:2d:21:0e:c9:41",
            "ip": "192.168.5.2",
            "createdAt": "2020-07-01 21:32:31"
        }
    ]
}
RESOURCE

Accounts

6 endpoint

Billing API / Accounts / Get All Accounts

Get All Accounts

API key · Header
GET https://api.ubill.dev /v1/accounts

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/accounts' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Get All Accounts Example
Response · JSON
{
    "statusID": 0,
    "message": "Success",
    "draw": 0,
    "recordsTotal": 70114,
    "recordsFiltered": 70114,
    "data": [
        {
            "id": "170115",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "თბილისი - თბილისი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": null,
            "tariffName": null,
            "tariffPrice": null,
            "balance": "0.00",
            "statusID": "1",
            "statusName": "აქტიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-12-02 11:41:37"
        },
        {
            "id": "170114",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "ბათუმი - ბათუმი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-2.00",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-11-20 23:56:52"
        }
    ]
}
Billing API / Accounts / Create Account

Create Account

API key · Header
POST https://api.ubill.dev /v1/accounts/create

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

FieldTypeRequiredDescription
customerIDintegeryesNumber of the customer the account belongs to, the same id returned by the customer endpoints.
namestring, max 50noAccount name.
birthDatestringnoDate in YYYY-MM-DD format.
areaIDintegernoSettlement identifier of the uBill district list.
addressstring, max 50noService address.
geoLocationstring, max 100noCoordinates in 41.732438,44.7688134 format.
column1, column2string, max 50noFree additional fields.
tariffIDintegernoTariff number of the company.
groupIDintegernoGroup or branch number of the company.
tagsIDarray of integersnoTag numbers of the company that are attached to the account.
numbersarraynoPhone 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.

FieldModuleRequiredDescription
macNetworkyesMAC address of the device, unique inside the company.
onuMacNetworknoONU MAC address, unique inside the company.
ipRangeIDNetworkyesNAS IP range number. The first free address of that range is assigned to the account automatically and returned as ip.
stbMacIPTVnoSTB MAC address, unique inside the company.
gpsProviderIDGPS trackyesGPS provider number of the company.
gpsTrackIdentifierGPS tracknoDevice 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

HTTPstatusIDDescription
2010Account created, data holds the new account.
400400Validation failed, the errors object names every invalid field. Duplicated MAC addresses and phone numbers are reported the same way.
50099The account could not be saved, nothing is written.

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "customerID": 100001,
    "name": "ბინა - ვაჟა-ფშაველას 1",
    "birthDate": "1990-05-17",
    "areaID": 1,
    "address": "ვაჟა-ფშაველას 1",
    "geoLocation": "41.732438,44.7688134",
    "column1": "",
    "column2": "",
    "tariffID": 2,
    "groupID": 1,
    "tagsID": [1, 3],
    "mac": "00:11:22:33:44:55",
    "onuMac": "AA:BB:CC:DD:EE:FF",
    "ipRangeID": 1,
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1
        }
    ]
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/accounts/create' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerID": 100001,
    "name": "ბინა - ვაჟა-ფშაველას 1",
    "birthDate": "1990-05-17",
    "areaID": 1,
    "address": "ვაჟა-ფშაველას 1",
    "geoLocation": "41.732438,44.7688134",
    "column1": "",
    "column2": "",
    "tariffID": 2,
    "groupID": 1,
    "tagsID": [1, 3],
    "mac": "00:11:22:33:44:55",
    "onuMac": "AA:BB:CC:DD:EE:FF",
    "ipRangeID": 1,
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1
        }
    ]
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "customerID": 100001,
    "name": "ბინა - ვაჟა-ფშაველას 1",
    "birthDate": "1990-05-17",
    "areaID": 1,
    "address": "ვაჟა-ფშაველას 1",
    "geoLocation": "41.732438,44.7688134",
    "column1": "",
    "column2": "",
    "tariffID": 2,
    "groupID": 1,
    "tagsID": [1, 3],
    "mac": "00:11:22:33:44:55",
    "onuMac": "AA:BB:CC:DD:EE:FF",
    "ipRangeID": 1,
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1
        }
    ]
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/create',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"customerID\": 100001,\n    \"name\": \"ბინა - ვაჟა-ფშაველას 1\",\n    \"birthDate\": \"1990-05-17\",\n    \"areaID\": 1,\n    \"address\": \"ვაჟა-ფშაველას 1\",\n    \"geoLocation\": \"41.732438,44.7688134\",\n    \"column1\": \"\",\n    \"column2\": \"\",\n    \"tariffID\": 2,\n    \"groupID\": 1,\n    \"tagsID\": [1, 3],\n    \"mac\": \"00:11:22:33:44:55\",\n    \"onuMac\": \"AA:BB:CC:DD:EE:FF\",\n    \"ipRangeID\": 1,\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": 1,\n            \"smsEnabled\": 1\n        }\n    ]\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

4 example
Account created 201
Response · JSON
{
    "statusID": 0,
    "message": "Account created",
    "data": {
        "id": 100001,
        "customerID": 100001,
        "name": "ბინა - ვაჟა-ფშაველას 1",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "mobile": "9955XXXXXXXX",
                "countryCode": "+995",
                "number": "5XXXXXXXX",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": null
            }
        ],
        "personalNo": "XXXXXXXXXXX",
        "birthDate": "1990-05-17",
        "areaID": 1,
        "area": "თბილისი",
        "address": "ვაჟა-ფშაველას 1",
        "geoLocation": "41.732438,44.7688134",
        "column1": "",
        "column2": "",
        "groupID": 1,
        "tagsID": [1, 3],
        "tariffID": 2,
        "balance": "0.00",
        "statusID": 1,
        "createdAt": "2026-08-26 13:19:39",
        "mac": "00:11:22:33:44:55",
        "onuMac": "AA:BB:CC:DD:EE:FF",
        "ipRangeID": 1,
        "ip": "192.168.5.21"
    }
}
Created without sms balance 201
Response · JSON
{
    "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 failed 400
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 used 400
Response · JSON
{
    "statusID": 400,
    "message": "Account creation failed",
    "data": null,
    "errors": {
        "account": [
            "ეს MAC მისამართი უკვე მითითებულია სხვა ანგარიშზე"
        ]
    }
}
Billing API / Accounts / Edit Account

Edit Account

API key · Header
POST https://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

FieldTypeDescription
namestring/null, max 50Name; null or empty string clears it.
birthDatestring/nullYYYY-MM-DD date; null or empty string clears it.
addressstring/null, max 50Address; null or empty string clears it.
column1, column2string/null, max 50Additional fields; null or empty string clears them.
numbersarrayReplacement phone number list; omission preserves existing numbers.
customerIDintegerCustomer id returned by the customer endpoints for your company. Cannot be null.
areaIDinteger/nullSettlement ID; null removes the settlement.
geoLocationstring/nullLatitude,longitude with latitude between -90 and 90 and longitude between -180 and 180; null or empty string clears it.
tariffID, groupIDinteger/nullPublic tariff/group IDs in the same company. Null removes the link.
tagsIDarray of integersFull replacement list of public tag IDs. [] removes all tags; omission preserves them.
mac, onuMacstring/null, max 45Available only with the Network module. Values must be unique within the company; null or empty string clears them.
ipRangeIDinteger/nullNetwork 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.
stbMacstring/null, max 45IPTV module only. Must be unique within the company.
gpsProviderIDinteger/nullGPS module only. Public GPS provider ID; null clears it.
gpsTrackIdentifierstring/null, max 255GPS module only. Unique device identifier; null or empty string clears it.
statusIDintegerAccount status: 1 = Active (აქტიური), 2 = Passive (პასიური), 3 = Suspended (შეჩერებული), 4 = Cancelled (გაუქმებული). Omission keeps the current status; null, strings and unknown IDs are rejected.

Account statuses / ანგარიშის სტატუსები

statusIDMeaningქართული მნიშვნელობა
1Activeაქტიური
2Passiveპასიური
3Suspendedშეჩერებული
4Cancelledგაუქმებული

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

HTTPstatusIDDescription
2000Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400400Invalid request or invalid field values. errors identifies the affected fields; data is null.
401401Invalid API key or missing edit permission.
403403The caller IP address is not allowed.
404404The record is missing, deleted, or belongs to another company.
415415The request Content-Type is not application/json.
429429API rate limit exceeded.
50099The update could not be saved. The previous data remains unchanged.

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "name": "Updated Account",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "address": "Updated service address",
    "statusID": 2
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/accounts/edit/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Account",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "address": "Updated service address",
    "statusID": 2
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/edit/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "name": "Updated Account",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "address": "Updated service address",
    "statusID": 2
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/edit/100001',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"name\": \"Updated Account\",\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": true,\n            \"smsEnabled\": true,\n            \"note\": \"Main number\"\n        },\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"smsEnabled\": false,\n            \"note\": \"Additional number\"\n        }\n    ],\n    \"address\": \"Updated service address\",\n    \"statusID\": 2\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

5 example
Updated 200
Response · JSON
{
    "statusID": 0,
    "message": "Account updated",
    "data": {
        "id": 100001,
        "name": "Updated Account",
        "birthDate": null,
        "address": "Updated service address",
        "column1": null,
        "column2": null,
        "createdAt": "2026-10-01 10:00:00",
        "updatedAt": "2026-10-27 12:00:00",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": "Main number",
                "mobile": "9955XXXXXXXX"
            },
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "smsEnabled": 0,
                "note": "Additional number",
                "mobile": "9955XXXXXXXX",
                "isPrimary": 0
            }
        ],
        "customerID": 100001,
        "areaID": null,
        "geoLocation": null,
        "balance": "12.34",
        "statusID": 2,
        "tariffID": null,
        "groupID": null,
        "ipRangeID": null,
        "gpsProviderID": null,
        "tagsID": [],
        "mac": null,
        "onuMac": null,
        "stbMac": null,
        "ip": null,
        "gpsTrackIdentifier": null,
        "statusName": "პასიური"
    }
}
Validation failed 400
Response · JSON
{
    "statusID": 400,
    "message": "Validation failed",
    "data": null,
    "errors": {
        "numbers": "Phone number is invalid"
    }
}
Not found 404
Response · JSON
{
    "statusID": 404,
    "message": "Account not found",
    "data": null
}
Storage failure 500
Response · JSON
{
    "statusID": 99,
    "message": "Account update failed",
    "data": null
}
Invalid account status 400
Response · JSON
{
    "statusID": 400,
    "message": "Validation failed",
    "data": null,
    "errors": {
        "statusID": "statusID does not exist"
    }
}
Billing API / Accounts / Get Account

Get Account

API key · Header
GET https://api.ubill.dev /v1/accounts/100001

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/accounts/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Get Account Example
Response · JSON
{
    "statusID": 0,
    "message": "Success",
    "data": [
        {
            "id": "100001",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "2",
            "area": "თბილისი",
            "address": "Example Address",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-9.00",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": "Cc:2d:21:0e:c9:41",
            "ip": "192.168.5.2",
            "createdAt": "2020-07-01 21:32:31"
        }
    ]
}
Billing API / Accounts / Accounts Search

Accounts Search

API key · Header
GET https://api.ubill.dev /v1/accounts/search?type=mobile&value=9955XXXXXXXX

URL parameters 2

typequerymobile
valuequery9955XXXXXXXX

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/accounts/search?type=mobile&value=9955XXXXXXXX' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/search?type=mobile&value=9955XXXXXXXX',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/search?type=mobile&value=9955XXXXXXXX',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

0 example
No response example is available for this endpoint.
Billing API / Accounts / Set Credit

Set Credit

API key · Header
POST https://api.ubill.dev /v1/accounts/setCredit

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "accountID": 170114,
    "date": "2023-12-10"
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/accounts/setCredit' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountID": 170114,
    "date": "2023-12-10"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/setCredit',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "accountID": 170114,
    "date": "2023-12-10"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/setCredit',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"accountID\": 170114,\n    \"date\": \"2023-12-10\"\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Set Credit Example
Response · JSON
{
    "statusID": 0,
    "message": "Success"
}
RESOURCE

Payments

3 endpoint

Billing API / Payments / Get Payments

Get Payments

API key · Header
GET https://api.ubill.dev /v1/payments

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/payments' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/payments',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/payments',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Get Payments Example
Response · JSON
{
    "status": true,
    "draw": 0,
    "recordsTotal": 9,
    "recordsFiltered": 9,
    "data": [
        {
            "id": "9",
            "accountID": "100001",
            "balance": "0.29",
            "sum": "-10.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-06-11 10:07:13"
        },
        {
            "id": "8",
            "accountID": "100001",
            "balance": "-0.71",
            "sum": "1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2022-06-10 22:24:14"
        },
        {
            "id": "7",
            "accountID": "170099",
            "balance": "-1.00",
            "sum": "20.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-01-29 16:39:50"
        },
        {
            "id": "6",
            "accountID": "170099",
            "balance": "0.00",
            "sum": "-1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-01-29 16:39:39"
        },
        {
            "id": "5",
            "accountID": "100001",
            "balance": "39.06",
            "sum": "10.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:16:43"
        },
        {
            "id": "4",
            "accountID": "100001",
            "balance": "-0.94",
            "sum": "20.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:14:57"
        },
        {
            "id": "3",
            "accountID": "100001",
            "balance": "0.06",
            "sum": "1.00",
            "comment": null,
            "transactionID": "t1",
            "paySystem": "TBCPAY",
            "apiStatus": "0",
            "typeID": "5",
            "typeName": "ჩარიცხვა",
            "admin": null,
            "date": "2021-11-13 15:26:53"
        },
        {
            "id": "2",
            "accountID": "100001",
            "balance": "-0.94",
            "sum": "1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:32"
        },
        {
            "id": "1",
            "accountID": "100001",
            "balance": "-1.94",
            "sum": "1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:14"
        }
    ]
}
Billing API / Payments / Get Payments by account

Get Payments by account

API key · Header
GET https://api.ubill.dev /v1/payments/account/100001

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Code examples

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/payments/account/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/payments/account/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/payments/account/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Get Payments by account Example
Response · JSON
{
    "statusID": 0,
    "message": "Success",
    "data": [
        {
            "id": "89",
            "accountID": null,
            "balance": "-1.94",
            "sum": "1",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:14"
        },
        {
            "id": "90",
            "accountID": null,
            "balance": "-0.94",
            "sum": "1",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:32"
        },
        {
            "id": "537",
            "accountID": null,
            "balance": "0.06",
            "sum": "1",
            "comment": null,
            "transactionID": "t1",
            "paySystem": "TBCPAY",
            "apiStatus": "0",
            "typeID": "5",
            "typeName": "ჩარიცხვა",
            "admin": null,
            "date": "2021-11-13 15:26:53"
        },
        {
            "id": "641",
            "accountID": null,
            "balance": "-0.94",
            "sum": "20",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:14:57"
        },
        {
            "id": "642",
            "accountID": null,
            "balance": "39.06",
            "sum": "10",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:16:43"
        },
        {
            "id": "1720",
            "accountID": null,
            "balance": "-0.7057142857142757",
            "sum": "1",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2022-06-10 22:24:14"
        },
        {
            "id": "1729",
            "accountID": null,
            "balance": "0.29428571428572",
            "sum": "-10",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-06-11 10:07:13"
        }
    ]
}
Billing API / Payments / Add Payment

Add Payment

API key · Header
POST https://api.ubill.dev /v1/payments/add

Request headers 2

KeyValueSource
keyYOUR_API_KEYAuthentication
Content-Typeapplication/jsonHeader

Request body JSON

Request body
{
    "accountID" : 170114,
    "sum" : 1,
    "comment": "text",
    "paySystem": "WEB"
}

Code examples

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/payments/add' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountID" : 170114,
    "sum" : 1,
    "comment": "text",
    "paySystem": "WEB"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/payments/add',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "accountID" : 170114,
    "sum" : 1,
    "comment": "text",
    "paySystem": "WEB"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/payments/add',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"accountID\" : 170114,\n    \"sum\" : 1,\n    \"comment\": \"text\",\n    \"paySystem\": \"WEB\"\n}"
  }
);

const data = await response.json();
console.log(data);

Response examples

1 example
Add Payments Example
Response · JSON
{
    "statusID": 0,
    "message": "Success",
    "data": {
        "id": "11521"
    }
}
NEED HELP?

Integration support

The uBill team can help with any API integration questions.

Contact us
Infrastructure & Technologies

We use leading and reliable technologies

uBill is built on modern tools that ensure stability, security, and seamless scalability

Back to top