Referrals · ModKey Docs

List referrals

POST https://dev.mod.wtf/api/v2/action

methodget-referrals

Same as get-users.

Body

soft_id integer optional

ID of a software you own; your main software when omitted

Errors it can return

validation + shared codes

POST /api/v2/action HTTP/1.1
Host: dev.mod.wtf
Content-Type: application/json
Accept: application/json

{
    "api_key": "YOUR_API_KEY",
    "method": "get-referrals"
}

curl -sS -X POST 'https://dev.mod.wtf/api/v2/action' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY",
    "method": "get-referrals"
}'

const response = await fetch("https://dev.mod.wtf/api/v2/action", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "api_key": "YOUR_API_KEY",
      "method": "get-referrals"
  }),
});

const result = await response.json();

$ch = curl_init('https://dev.mod.wtf/api/v2/action');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'YOUR_API_KEY',
        'method' => 'get-referrals',
    ]),
]);

$result = json_decode(curl_exec($ch), true);

import requests

response = requests.post(
    "https://dev.mod.wtf/api/v2/action",
    json={
        "api_key": "YOUR_API_KEY",
        "method": "get-referrals",
    },
    timeout=10,
)

result = response.json()

{
    "ok": true,
    "data": {
        "total": 8,
        "limit": 50,
        "offset": 0,
        "items": [
            {
                "id": 50,
                "username": "myreseller1",
                "fullname": "Reseller One",
                "email": "res@example.com",
                "level": 3,
                "level_label": "Reseller",
                "status": 1,
                "saldo": 1000,
                "uplink": "JohnDoe",
                "soft": 123,
                "created_at": "2025-03-01 09:00:00",
                "expiration_date": "2026-03-01 09:00:00",
                "telegram": null,
                "telegram_id": null
            }
        ]
    }
}

{
    "ok": false,
    "error": "unauthorized",
    "message": "Invalid or missing api_key"
}

Create referral

POST https://dev.mod.wtf/api/v2/action

methodcreate-referral

Same as create-user; level defaults to 2 (Admin). In software you created, level 4 adds a Software owner.

Body

username string required

4-25 alphanumeric chars
password string required

8-128 chars
level integer optional

2 Admin or 3 Reseller, default 2. 4 Software owner only in software you created
email string optional

Up to 40 characters; a placeholder address is generated when omitted
fullname string optional

Up to 155 characters: letters, digits, spaces, periods, apostrophes and hyphens
expiration_days integer optional

0 to 18250. Admin and Reseller default to 30 days. Software owners never expire
soft_id integer optional

ID of a software you own; your main software when omitted

Errors it can return

forbidden_field forbidden_soft duplicate validation database_error + shared codes

POST /api/v2/action HTTP/1.1
Host: dev.mod.wtf
Content-Type: application/json
Accept: application/json

{
    "api_key": "YOUR_API_KEY",
    "method": "create-referral",
    "username": "newpartner",
    "password": "abcd1234",
    "expiration_days": 30
}

curl -sS -X POST 'https://dev.mod.wtf/api/v2/action' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY",
    "method": "create-referral",
    "username": "newpartner",
    "password": "abcd1234",
    "expiration_days": 30
}'

const response = await fetch("https://dev.mod.wtf/api/v2/action", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "api_key": "YOUR_API_KEY",
      "method": "create-referral",
      "username": "newpartner",
      "password": "abcd1234",
      "expiration_days": 30
  }),
});

const result = await response.json();

$ch = curl_init('https://dev.mod.wtf/api/v2/action');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'YOUR_API_KEY',
        'method' => 'create-referral',
        'username' => 'newpartner',
        'password' => 'abcd1234',
        'expiration_days' => 30,
    ]),
]);

$result = json_decode(curl_exec($ch), true);

import requests

response = requests.post(
    "https://dev.mod.wtf/api/v2/action",
    json={
        "api_key": "YOUR_API_KEY",
        "method": "create-referral",
        "username": "newpartner",
        "password": "abcd1234",
        "expiration_days": 30,
    },
    timeout=10,
)

result = response.json()

{
    "ok": true,
    "data": {
        "id": 51,
        "username": "newpartner",
        "fullname": "",
        "email": "ue2a994e09598@m.dk",
        "level": 2,
        "level_label": "Admin",
        "status": 1,
        "saldo": 0,
        "uplink": "JohnDoe",
        "soft": 123,
        "created_at": "2025-06-01 12:00:00",
        "expiration_date": "2025-07-01 12:00:00",
        "telegram": null,
        "telegram_id": null
    }
}

{
    "ok": false,
    "error": "validation",
    "message": "username must be 4-25 alphanumeric characters"
}

{
    "ok": false,
    "error": "unauthorized",
    "message": "Invalid or missing api_key"
}

List referral codes

POST https://dev.mod.wtf/api/v2/action

methodget-referral-codes

List sign-up codes of a software. used=0 for free codes, used=1 for used ones.

Body

soft_id integer optional

ID of a software you own; default is your main software
used integer optional

0 or 1
limit integer optional

1-200, default 50
offset integer optional

Default 0

Errors it can return

validation + shared codes

POST /api/v2/action HTTP/1.1
Host: dev.mod.wtf
Content-Type: application/json
Accept: application/json

{
    "api_key": "YOUR_API_KEY",
    "method": "get-referral-codes",
    "used": 0
}

curl -sS -X POST 'https://dev.mod.wtf/api/v2/action' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY",
    "method": "get-referral-codes",
    "used": 0
}'

const response = await fetch("https://dev.mod.wtf/api/v2/action", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "api_key": "YOUR_API_KEY",
      "method": "get-referral-codes",
      "used": 0
  }),
});

const result = await response.json();

$ch = curl_init('https://dev.mod.wtf/api/v2/action');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'YOUR_API_KEY',
        'method' => 'get-referral-codes',
        'used' => 0,
    ]),
]);

$result = json_decode(curl_exec($ch), true);

import requests

response = requests.post(
    "https://dev.mod.wtf/api/v2/action",
    json={
        "api_key": "YOUR_API_KEY",
        "method": "get-referral-codes",
        "used": 0,
    },
    timeout=10,
)

result = response.json()

{
    "ok": true,
    "data": {
        "total": 1,
        "limit": 50,
        "offset": 0,
        "items": [
            {
                "id": 9,
                "code": "Hq7tPzW3mKa9RbXe",
                "level": 3,
                "role": "Reseller",
                "soft_id": 123,
                "saldo": 500,
                "account_expires": "2026-12-01 12:00:00",
                "used_by": null,
                "created_by": "JohnDoe"
            }
        ]
    }
}

{
    "ok": false,
    "error": "validation",
    "message": "used must be 0 or 1"
}

{
    "ok": false,
    "error": "unauthorized",
    "message": "Invalid or missing api_key"
}

Create referral code

POST https://dev.mod.wtf/api/v2/action

methodcreate-referral-code

Create a one-time sign-up code. It sets the role, balance and account term of whoever signs up with it.

Body

soft_id integer optional

ID of a software you own; default is your main software
level integer optional

2 Admin or 3 Reseller, 4 only in software you created; default 3
saldo integer optional

Starting balance, default 0
days integer optional

1, 3, 7, 14, 30, 60, 90, 180, 365 or 0 for lifetime; default 30

Errors it can return

validation + shared codes

POST /api/v2/action HTTP/1.1
Host: dev.mod.wtf
Content-Type: application/json
Accept: application/json

{
    "api_key": "YOUR_API_KEY",
    "method": "create-referral-code",
    "level": 3,
    "saldo": 500,
    "days": 30
}

curl -sS -X POST 'https://dev.mod.wtf/api/v2/action' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY",
    "method": "create-referral-code",
    "level": 3,
    "saldo": 500,
    "days": 30
}'

const response = await fetch("https://dev.mod.wtf/api/v2/action", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "api_key": "YOUR_API_KEY",
      "method": "create-referral-code",
      "level": 3,
      "saldo": 500,
      "days": 30
  }),
});

const result = await response.json();

$ch = curl_init('https://dev.mod.wtf/api/v2/action');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'YOUR_API_KEY',
        'method' => 'create-referral-code',
        'level' => 3,
        'saldo' => 500,
        'days' => 30,
    ]),
]);

$result = json_decode(curl_exec($ch), true);

import requests

response = requests.post(
    "https://dev.mod.wtf/api/v2/action",
    json={
        "api_key": "YOUR_API_KEY",
        "method": "create-referral-code",
        "level": 3,
        "saldo": 500,
        "days": 30,
    },
    timeout=10,
)

result = response.json()

{
    "ok": true,
    "data": {
        "id": 9,
        "code": "Hq7tPzW3mKa9RbXe",
        "level": 3,
        "role": "Reseller",
        "soft_id": 123,
        "saldo": 500,
        "account_expires": "2026-12-01 12:00:00",
        "used_by": null,
        "created_by": "JohnDoe"
    }
}

{
    "ok": false,
    "error": "forbidden",
    "message": "You cannot assign this role."
}

{
    "ok": false,
    "error": "unauthorized",
    "message": "Invalid or missing api_key"
}

Delete referral code

POST https://dev.mod.wtf/api/v2/action

methoddelete-referral-code

Delete an unused code. Used codes stay in history.

Body

code_id integer required

Code ID from get-referral-codes
soft_id integer optional

ID of a software you own; your main software when omitted

Errors it can return

validation + shared codes

POST /api/v2/action HTTP/1.1
Host: dev.mod.wtf
Content-Type: application/json
Accept: application/json

{
    "api_key": "YOUR_API_KEY",
    "method": "delete-referral-code",
    "code_id": 9
}

curl -sS -X POST 'https://dev.mod.wtf/api/v2/action' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY",
    "method": "delete-referral-code",
    "code_id": 9
}'

const response = await fetch("https://dev.mod.wtf/api/v2/action", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "api_key": "YOUR_API_KEY",
      "method": "delete-referral-code",
      "code_id": 9
  }),
});

const result = await response.json();

$ch = curl_init('https://dev.mod.wtf/api/v2/action');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'YOUR_API_KEY',
        'method' => 'delete-referral-code',
        'code_id' => 9,
    ]),
]);

$result = json_decode(curl_exec($ch), true);

import requests

response = requests.post(
    "https://dev.mod.wtf/api/v2/action",
    json={
        "api_key": "YOUR_API_KEY",
        "method": "delete-referral-code",
        "code_id": 9,
    },
    timeout=10,
)

result = response.json()

{
    "ok": true,
    "data": {
        "id": 9,
        "deleted": true
    }
}

{
    "ok": false,
    "error": "scope_changed",
    "message": "This code has been used and must remain in history."
}

{
    "ok": false,
    "error": "unauthorized",
    "message": "Invalid or missing api_key"
}

#Keep in mind

#List referrals

Body

Errors it can return

#Create referral

Body

Errors it can return

#List referral codes

Body

Errors it can return

#Create referral code

Body

Errors it can return

#Delete referral code

Body

Errors it can return

Keep in mind

List referrals

Create referral

List referral codes

Create referral code

Delete referral code