Get User Balance

GET /v1/users/:userId/balance

Returns a user’s full profile including balance, display name, email, metadata, and account creation date. This is the detailed server-side variant; see Get User Balance (SDK) for the lightweight client-side version.

Authentication

Header	Required	Value
X-API-Secret	Yes	Your secret key

Path Parameters

Param	Type	Description
userId	string	The user’s external ID

Request Examples

cURL

curl -X GET https://api.gamifyhost.com/v1/users/user_12345/balance \
  -H "X-API-Secret: sk_live_your_secret_key"

JavaScript

const userId = 'user_12345';

const response = await fetch(
  `https://api.gamifyhost.com/v1/users/${userId}/balance`,
  {
    method: 'GET',
    headers: {
      'X-API-Secret': 'sk_live_your_secret_key',
    },
  }
);

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

Python

import requests

user_id = "user_12345"

response = requests.get(
    f"https://api.gamifyhost.com/v1/users/{user_id}/balance",
    headers={"X-API-Secret": "sk_live_your_secret_key"},
)

data = response.json()
print(f"{data['data']['displayName']}: {data['data']['totalPoints']} pts")

Java

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

String userId = "user_12345";

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/users/" + userId + "/balance"))
    .header("X-API-Secret", "sk_live_your_secret_key")
    .GET()
    .build();

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

Go

userId := "user_12345"
url := fmt.Sprintf("https://api.gamifyhost.com/v1/users/%s/balance", userId)

req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("X-API-Secret", "sk_live_your_secret_key")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

PHP

$userId = 'user_12345';

$ch = curl_init("https://api.gamifyhost.com/v1/users/{$userId}/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Secret: sk_live_your_secret_key',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "{$data['data']['displayName']}: {$data['data']['totalPoints']} pts\n";

Ruby

require 'net/http'
require 'json'

user_id = 'user_12345'

uri = URI("https://api.gamifyhost.com/v1/users/#{user_id}/balance")
req = Net::HTTP::Get.new(uri)
req['X-API-Secret'] = 'sk_live_your_secret_key'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts "#{data['data']['displayName']}: #{data['data']['totalPoints']} pts"

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Secret", "sk_live_your_secret_key");

var userId = "user_12345";
var response = await client.GetAsync($"https://api.gamifyhost.com/v1/users/{userId}/balance");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Dart

import 'dart:convert';
import 'package:http/http.dart' as http;

const userId = 'user_12345';

final response = await http.get(
  Uri.parse('https://api.gamifyhost.com/v1/users/$userId/balance'),
  headers: {'X-API-Secret': 'sk_live_your_secret_key'},
);

final data = jsonDecode(response.body);
print('${data['data']['displayName']}: ${data['data']['totalPoints']} pts');

Response

Status: 200 OK

{
  "message": "User balance retrieved",
  "code": 200,
  "status": "success",
  "data": {
    "userId": "user_12345",
    "totalPoints": 5500,
    "displayName": "Alice",
    "email": "alice@example.com",
    "metadata": {
      "source": "ios_app"
    },
    "createdAt": "2025-06-01T08:00:00Z"
  }
}

Response Fields

Field	Type	Description
userId	string	The user’s external ID
totalPoints	integer	Current point balance
displayName	string	Display name
email	string	Email address
metadata	object	User metadata
createdAt	datetime	Account creation timestamp

Errors

Code	Message
404	User not found