A referral code lets someone sign up. A user's code attaches that user as the new account's referrer; an admin code (is_admin: true) attaches none. Every account holds one primary code.
Codes are 3 to 32 characters of lowercase letters, digits, - and _. Code date-times are UTC without an offset.
- GET
/admin/referral-codes/list - GET
/admin/referral-codes/{code}/uses - POST
/admin/referral-codes/create - POST
/admin/referral-codes/grant - POST
/admin/referral-codes/update - POST
/admin/referral-codes/revoke - POST
/admin/referral-codes/delete - GET
/admin/users/{account_id}/referral-series - GET
/admin/referral/overview
The Referral code object
A referral code as listed to admins.
Attributes
-
codestringThe code. -
is_adminbooleanAdmin code, which attaches no referrer. -
is_primarybooleanThe owner's primary code. -
statusenumCode status. Revoked codes are inactive.Possible valuesactiverevokedexhaustedexpired -
use_limitinteger | nullAllowed signups.nullmeans unlimited. -
uses_countintegerSignups so far. -
remaining_usesinteger | nullSignups left.nullwhen unlimited. -
expires_atstring | nullExpiry. -
labelstring | nullAdmin note. -
created_atstringCreation time. -
owner_license_keystring | nullLicense key of the owner.nullfor admin codes.
List referral codes
/admin/referral-codes/list Returns a filtered page of referral codes.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Query parameters
-
statusenum OptionalCode status. The client leaves it out for all statuses.Possible valuesactiverevokedexhaustedexpired -
ownerstring OptionalOwner's username. -
is_adminboolean Optionaltruelists only admin codes,falseleaves them out. -
searchstring OptionalPart of the code, case-insensitive. -
owner_searchstring OptionalPart of the owner's username or license key, case-insensitive. -
limitinteger OptionalPage size. The API defaults to 50 and caps at 500. -
offsetinteger OptionalNumber of rows to skip.
Returns 200 OK · application/json
-
codesarray<object>Codes on this page. See Referral code. -
totalintegerTotal number of matching codes. -
limitintegerApplied page size. -
offsetintegerApplied offset.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | Unknown status. Send active, revoked, exhausted or expired, or leave status out. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.admin.listReferralCodes(query) src/lib/proxima/endpoints/admin.ts
List a referral code's uses
/admin/referral-codes/{code}/uses Returns the signups made with a code, newest first.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Path parameters
-
codestring RequiredThe code.
Returns 200 OK · application/json
-
codestringThe code. -
usesarray<object>Signups, newest first.Child attributes 2
-
consumed_bystringLicense key created with the code. -
consumed_atstringSignup time, UTC.
-
Errors
Only the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.admin.getReferralCodeUses(code) src/lib/proxima/endpoints/admin.ts
Create an admin referral code
/admin/referral-codes/create Creates an admin code, which lets people sign up without a referrer.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying With a custom
code, a repeat fails withcode already in use. A random code is created anew on each call, so look for it with List referral codes (is_admin=true) first.
Body parameters application/json
-
codestring OptionalCustom code. Omit it for a random one. -
use_limitinteger OptionalNumber of signups allowed, 1 to 10000. Omitted means single-use. -
use_limit_unlimitedboolean Optionaltruefor unlimited uses. Overridesuse_limit. -
labelstring OptionalAdmin note, up to 20 characters. -
expires_atstring OptionalExpiry, as a UTC date-time without offset (YYYY-MM-DDTHH:MM:SS).
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
codestringThe code created. -
use_limitinteger | nullAllowed signups.nullmeans unlimited.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The custom code has a character outside a-z, 0-9, - and _. Other format messages: referral code must be 3-32 chars, that referral code is reserved. Send 3 to 32 lowercase letters, digits, - or _, and avoid reserved words. |
| 400 | bad_request | The custom code already exists. Choose another code, or leave code out for a random one. |
| 400 | bad_request | label is longer than 20 characters. Shorten label to 20 characters. |
| 400 | bad_request | use_limit is outside 1 to 10000. Send a use_limit from 1 to 10000, or use_limit_unlimited: true. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.admin.createReferralCode(request) src/lib/proxima/endpoints/admin.ts
Grant referral codes
/admin/referral-codes/grant Issues extra referral codes to a user.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying A lost call may have issued the codes, and a repeat issues new random ones. Look for the user's codes with List referral codes (
owner) before retrying.
Grants a batch of random single-use codes, custom codes, or both. Granted codes attach that user as referrer.
Body parameters application/json
-
usernamestring RequiredUser who receives the codes. -
single_use_countinteger OptionalNumber of random single-use codes, up to 100. -
customarray<object> OptionalCustom codes.Child attributes 5
-
codestring OptionalCustom code. Omit it for a random one. -
use_limitinteger OptionalNumber of signups allowed, 1 to 10000. Omitted means single-use. -
use_limit_unlimitedboolean Optionaltruefor unlimited uses. Overridesuse_limit. -
labelstring OptionalAdmin note, up to 20 characters. -
expires_atstring OptionalExpiry, as a UTC date-time without offset (YYYY-MM-DDTHH:MM:SS).
-
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
usernamestringUser who received the codes. -
issuedarray<string>Codes issued.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 404 | not_found | No account has this username. Use a username returned by List users. |
| 400 | bad_request | single_use_count is 0 and custom is empty. Set single_use_count above 0 or add a custom entry. |
| 400 | bad_request | single_use_count is above 100. Grant at most 100 single-use codes per call. |
| 400 | bad_request | A custom code is malformed. Other messages for a custom entry: referral code must be 3-32 chars, that referral code is reserved, label must be <= 20 chars, use_limit must be 1-10000 or unlimited. Nothing is granted. Give each custom entry a valid code, a label of up to 20 characters and a use_limit from 1 to 10000. |
| 400 | bad_request | A custom code already exists. Nothing is granted: the batch is all or nothing. Choose another custom code, or leave code out of the entry for a random one. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.admin.grantReferralCodes(request) src/lib/proxima/endpoints/admin.ts
Update a referral code
/admin/referral-codes/update Changes a code's label, expiry, use limit or active state.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry The call sets values, so a repeat changes nothing.
Omitted fields stay unchanged; null clears label or expires_at and makes use_limit unlimited. is_active: true reactivates a revoked code.
Body parameters application/json
-
codestring RequiredThe code. -
labelstring | null OptionalAdmin note, up to 20 characters. -
expires_atstring | null OptionalExpiry, as a UTC date-time without offset. -
use_limitinteger | null OptionalAllowed signups, 1 to 10000.nullmeans unlimited. -
is_activeboolean Optionalfalserevokes the code,truereactivates it.
Returns 200 OK · application/json
-
okbooleanAlwaystrue.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The body changes no field. Send at least one of label, expires_at, use_limit or is_active. |
| 400 | bad_request | use_limit is outside 1 to 10000. A label over 20 characters answers label must be <= 20 chars. Send a use_limit from 1 to 10000, or null for unlimited, and a label of up to 20 characters. |
| 404 | not_found | The code does not exist. Use a code returned by List referral codes. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.admin.updateReferralCode(request) src/lib/proxima/endpoints/admin.ts
Revoke a referral code
/admin/referral-codes/revoke Deactivates a code so it can no longer be used.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Revoking a revoked code succeeds again.
The code and its use history stay. Reactivate it with Update a referral code.
Body parameters application/json
-
codestring RequiredThe code.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
codestringThe code revoked.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 404 | not_found | The code does not exist. Use a code returned by List referral codes. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.admin.revokeReferralCode(code) src/lib/proxima/endpoints/admin.ts
Delete a referral code
/admin/referral-codes/delete Deletes a code and its use history, freeing its name.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Once the code is gone, a repeat answers
404.
Accounts that signed up with the code keep their referrer. Deleting a primary code issues its owner a new random primary code.
Body parameters application/json
-
codestring RequiredThe code.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
codestringThe code deleted. -
replacement_codestring | nullNew primary code issued to the owner when the deleted code was their primary.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | code is empty. Send the code to delete. |
| 404 | not_found | The code does not exist. Use a code returned by List referral codes. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.admin.deleteReferralCode(code) src/lib/proxima/endpoints/admin.ts
Retrieve an account's referral series
/admin/users/{account_id}/referral-series Returns an account's referral downline and revenue over time, by level.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The admin view of the series an account reads for itself on its referral page.
Path parameters
-
account_idstring RequiredAccount id.
Query parameters
-
frominteger OptionalWindow start, Unix seconds. -
tointeger OptionalWindow end, Unix seconds. -
granularityenum OptionalBucket size.Possible valueshourdayweekmonth
Returns 200 OK · application/json
-
granularityenumBucket size applied.Possible valueshourdayweekmonth -
frominteger | nullWindow start applied, Unix seconds. -
tointeger | nullWindow end applied, Unix seconds. -
bucketsarray<object>One entry per bucket.Child attributes 5
-
bucket_startintegerBucket start, Unix seconds. -
new_referredintegerNew accounts at level 1. -
referral_revenue_usdstringSum ofrevenue_usd_by_level, in micro-USD, as an integer string. -
users_by_levelarray<object>Downline size per level:level,users. -
revenue_usd_by_levelarray<object>Referral revenue per level:level,usd(micro-USD string).
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 404 | not_found | No account has this account_id. Take the account_id from List users. |
| 400 | bad_request | granularity is not hour, day, week or month. Send granularity as hour, day, week or month. |
| 400 | bad_request | from is later than to. A bound that cannot be read as a date answers invalid from or invalid to. Send a from earlier than to. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.admin.getReferralSeries(accountId, params) src/lib/proxima/endpoints/admin.ts
Retrieve the referral overview
/admin/referral/overview Returns every account's referrer link and daily launch and referral activity.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The raw rows the admin referral overview builds its trees and totals from.
Query parameters
-
start_atinteger OptionalWindow start, Unix seconds. -
end_atinteger OptionalWindow end, Unix seconds. -
chain_idstring OptionalRestricts activity to one chain. -
currencyenum OptionalUnit ofgrossandreferral.Possible valuesusdnative
Returns 200 OK · application/json
-
currencyenumUnit applied.Possible valuesusdnative -
usersarray<object>Accounts.Child attributes 5
-
license_keystringLicense key. -
usernamestring | nullUsername. -
referrer_keystring | nullReferrer's license key. -
is_internalbooleanInternal account. -
created_atinteger | nullCreation time, Unix seconds.
-
-
activityarray<object>Activity per account, chain and day.Child attributes 6
-
license_keystringLicense key. -
chain_idstringChain id. -
bucketintegerDay start in UTC+1, Unix seconds. -
launchesintegerLaunches that day. -
grossstringFees paid, in the requestedcurrency(micro-USD, or lamports or wei), as an integer string. -
referralstringReferral generated, in the requestedcurrency(micro-USD, or lamports or wei), as an integer string.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | currency is not usd or native. Send currency=usd or currency=native. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.admin.getReferralOverview(params) src/lib/proxima/endpoints/admin.ts