Get balance

Current account balance.

GET  /api/v1/user/balance  · Permission: balance.read

Request

cURL

curl https://restlink23telecom.com/api/v1/user/balance \
  -H "X-API-Key: $API_KEY"

Node.js

const res = await fetch('https://restlink23telecom.com/api/v1/user/balance', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.API_KEY },
});

if (!res.ok) {
  const err = await res.json();
  throw new Error(`${err.error_code}: ${err.description}`);
}
const data = await res.json();
console.log(data);

Python

import os
import requests

res = requests.get(
    "https://restlink23telecom.com/api/v1/user/balance",
    headers={"X-API-Key": os.environ["API_KEY"]},
)
res.raise_for_status()
print(res.json())

PHP

<?php
$ch = curl_init('https://restlink23telecom.com/api/v1/user/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('API_KEY')],
]);

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

if ($status !== 200) {
    throw new Exception("HTTP $status: $response");
}
$data = json_decode($response, true);
print_r($data);

Ruby

require "net/http"
require "json"

uri = URI("https://restlink23telecom.com/api/v1/user/balance")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = ENV.fetch("API_KEY")

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)

puts JSON.parse(res.body)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://restlink23telecom.com/api/v1/user/balance"))
    .header("X-API-Key", System.getenv("API_KEY"))
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  req, err := http.NewRequest("GET", "https://restlink23telecom.com/api/v1/user/balance", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("X-API-Key", os.Getenv("API_KEY"))

  res, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

.NET

using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key",
    Environment.GetEnvironmentVariable("API_KEY"));

var response = await client.GetAsync("https://restlink23telecom.com/api/v1/user/balance");

response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

200 OK

{
  "balance": 1250.50,
  "currency": "EUR",
  "updated": "2026.02.13 10:15:00"
}

When the balance is zero or negative, the response additionally contains "credit_blocked": true — SMS sending is blocked until you top up.

Account still in setup?

During onboarding this endpoint returns HTTP 200 with {"status": false, "error": "Account is in setup process", …} — treat it as “not ready yet”, not as an error.

Balance checks on send

Every send request is pre-checked against your balance. If it would exceed the available funds you get 402 INSUFFICIENT_BALANCE with the estimated cost breakdown:

402 Payment Required

{
  "status": false,
  "error_code": "INSUFFICIENT_BALANCE",
  "description": "Insufficient balance",
  "balance": 0.42,
  "estimated_cost": 1.07,
  "currency": "EUR",
  "total_recipients": 100,
  "billable_recipients": 98,
  "segments": 2
}

Degraded state

Balance, pricing and payments are served from a background-refreshed cache. If the cache is unavailable, the API still returns HTTP 200 but flags degradation via response headers:

Header	Values	Meaning
X-Sms-Gateway-Status	partial, unavailable	Data quality indicator
X-Sms-Gateway-Reason	cache_disabled, cache_miss_refresh_failed	Machine-readable reason

These headers are absent on healthy responses. Degraded balance responses look like {"balance": 0, "currency": "EUR", "unavailable": true, "reason": "…"} — check the unavailable flag before alerting on a zero balance.

Monitoring recommendation

Poll balance once every few minutes at most (the cache refreshes on its own cadence), alert on credit_blocked: true, and ignore zero-balance readings that carry the unavailable: true flag.