TriportRPC
DashboardDocs

GET /v1/admin/referrals/users/{user_id} — Operator view of a user

GEThttps://api.triport.io/v1/admin/referrals/users/3f8c2a1e-9b4d-4c7a-8e21-6f0a1b2c3d4e

Operator-only lookup that returns a single user's full referral state — tier, code, paid-invitee count, balance, and their most recent attribution audit rows — in one call.

—— (operator token grants full access)—

GET /v1/admin/referrals/users/{user_id} is the operator (support/back-office) view of a single user's referral standing. It combines the user's referral overview — tier, label, commission rate, primary code, optional custom slug, paid-invitee count, and earnings balance — with the tail of their attribution audit log, so an operator can see both where the user stands now and how they got there in a single response.

This is an admin-surface endpoint: it is gated by a shared X-Admin-Token header rather than a user session cookie or an API key. There is no per-user authentication — the token authorizes the operator to read any user by id. Keep the token server-side; never ship it to a browser.

The recent_attributions array carries up to 50 of the most recent Attribution rows for the user (signup, first-paid, rejected, and tier-changed events). Monetary fields in balance are integers in micro-units (millionths of the account currency) — divide by 1,000,000 for the display value.

Parameters

Path parameters

user_idstring (UUID)required
The user to inspect. Must be a valid UUID; anything else returns 400 invalid_user_id.

Response

When the user has no custom slug, custom_slug is null. When the user has no attribution history, recent_attributions is an empty array ([]), never null.

user_idstring (UUID)
The inspected user's id (echoes the path parameter).
tierinteger
Numeric referral tier the user has reached.
tier_labelstring
Human-readable label for tier (e.g. "Silver").
rate_bpsinteger
Commission rate in basis points (1500 = 15%).
primary_codestring
The user's always-available referral code.
custom_slugstring | null
User-chosen vanity slug, or null if none is set.
paid_invitees_infointeger
Count of the user's invitees who have become paying customers.
balanceobject
Earnings balance, in micro-units (see below).
balance.pending_microinteger
Earned but not yet unlocked, in micro-units.
balance.available_microinteger
Unlocked and available to spend or withdraw, in micro-units.
balance.lifetime_microinteger
Total earned across the account's lifetime, in micro-units.
recent_attributionsarray
Up to 50 most recent attribution audit rows (newest first).

Errors

CodeMeaningWhen it happens
401admin_token_unsetThe server has no operator token configured; the admin surface is disabled.
401admin_token_invalidThe X-Admin-Token header is missing or does not match the configured token.
400invalid_user_idThe {user_id} path segment is not a valid UUID.
405method_not_allowedA non-GET method was used on this exact path.
500internalAn unexpected server-side error occurred while loading the overview or attribution rows.

See errors.md for the full error envelope and shared conventions.

Examples

JavaScript (fetch)

const userId = "3f8c2a1e-9b4d-4c7a-8e21-6f0a1b2c3d4e";


const res = await fetch(
  `https://api.triport.io/v1/admin/referrals/users/${userId}`,
  {
    headers: {
      "X-Admin-Token": process.env.TRIPORT_ADMIN_TOKEN,
      "Content-Type": "application/json",
    },
  },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const view = await res.json();
console.log(view.tier_label, view.balance.available_micro);
console.log(`${view.recent_attributions.length} recent events`);

TypeScript SDK (@triport/sdk)

import { TriportAdmin } from "@triport/sdk";


const admin = new TriportAdmin({
  baseUrl: "https://api.triport.io",
  adminToken: process.env.TRIPORT_ADMIN_TOKEN!,
});


const view = await admin.referrals.getUser(
  "3f8c2a1e-9b4d-4c7a-8e21-6f0a1b2c3d4e",
);
console.log(view.tierLabel, view.paidInviteesInfo);

Python (triport-sdk)

import os
from triport import TriportAdmin


admin = TriportAdmin(
    base_url="https://api.triport.io",
    admin_token=os.environ["TRIPORT_ADMIN_TOKEN"],
)


view = admin.referrals.get_user("3f8c2a1e-9b4d-4c7a-8e21-6f0a1b2c3d4e")
print(view["tier_label"], view["balance"]["available_micro"])
for att in view["recent_attributions"]:
    print(att["Event"], att["CreatedAt"])

Notes

  • Admin surface, not user surface. This route lives under /v1/admin/referrals/* and is authorized solely by X-Admin-Token. It is not callable with a user session cookie or a Bearer API key. Keep the token server-side.
  • Attribution field casing. recent_attributions rows use Go-style PascalCase keys (ID, UserID, Event, …), unlike the snake_case used elsewhere in this response. Match them exactly when parsing.
  • Fixed page size. The attribution tail is capped at 50 rows and is not paginated; it is intended as a quick audit context, not a full history export.
  • Micro-units. Every *_micro field is an integer in millionths. Format for display as value / 1_000_000.
  • Related operator endpoints. Set a user's tier with POST /v1/admin/referrals/users/{user_id}/tier, and drive payout lifecycle with POST /v1/admin/referrals/payouts/{id}/sent and .../failed. The retired POST /v1/admin/referrals/simulate-paid now returns 410 Gone.