API reference · v1

Build on Join4Join

The public API lets you run Join4Join inside your own Discord bot: register users, list servers to discover, claim daily rewards, create campaigns and transfer coins. Every user you bring earns you coins.

Base URL https://join4join.xyz/api/v1

Get your API key Example bot on GitHub

Introduction

01
Get your key

Generate an API key on the Developers page of your dashboard.
02
Send POST requests

Every endpoint is a POST with a JSON body and your key in the Authorization header.
03
Earn from your users

Users created through your key are affiliated to you: 0.1 coins for every server they join.

Open-source example bot A complete Node.js Discord bot built on this API. Fork it and make it yours. Free hosting for your bot Run your bot 24/7 for free on bot-hosting.net, our hosting partner.

Authentication

Send your API key as is (no Bearer prefix) in the Authorization header of every request. Requests are made on behalf of the key owner, you.

Authenticated request

curl -X POST "https://join4join.xyz/api/v1/developer/stats" \
  -H "Authorization: YOUR_API_KEY"

Keep your key secret: call the API from your bot or server, never from a browser or a public repository. If it leaks, regenerate it on the Developers page, the old key stops working immediately.

Responses & limits

Every response is JSON with a success boolean. Errors are returned with HTTP status 200, success: false and a human readable message, so always check success before reading data.

Error response

{
  "success": false,
  "message": "Api Key invalid."
}

Rate limit

50/ min

Requests per minute, per API key owner.

Common messages

Missing authorization header. No key sent.
Api Key invalid. Unknown, revoked or suspended key.
You have exceeded the 50 requests per minute limit. Wait a moment and retry.

Developer rewards

Every user created through your API key (with user/create or automatically by any endpoint that takes a user_id) is affiliated to you. Each time one of them joins a server through Join4Join, you earn 0.1 coins, for as long as they use the platform. Joins made by alt accounts do not count.

Follow your numbers with developer/stats or on the Developers page of your dashboard.

Community bots

Don't want to write or host code? Lend the token of your own Discord bot on the Developers page: Join4Join runs it for you with the full set of Join4Join slash commands. Users who start using Join4Join through your bot are affiliated to you, and you can claim 5 coins every day while it is online.

Add your bot Invite a community bot

Users

Create a user

POST /api/v1/user/create

Creates a Join4Join account for a Discord user. The account is affiliated to you: you earn 0.1 coins for every server this user joins.

Body parameters

Field	Type	Description
`user_id` required	string	Discord ID of the user.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/user/create" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123456789012345678"
  }'

Example response

JSON

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "coins": 0,
    "transactions": [],
    "owner": false
  }
}

Response fields

Field	Type	Description
`data.id`	string	Discord ID of the created user.
`data.coins`	number	Coin balance (0 for a new account).
`data.transactions`	array	Always empty for a new account.
`data.owner`	boolean	true when user_id is the owner of the API key.

Optional: every endpoint that takes a user_id also creates the account when needed. Use it when you want to register users explicitly, for example in a sign-up command.

Possible error messages (3)

Missing user_id params in the body.
This user has already an account.
This ID doesn't have a discord account.

Get a user

POST /api/v1/user/get

Returns the coin balance of a user and their 20 most recent transactions.

Body parameters

Field	Type	Description
`user_id` required	string	Discord ID of the user.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/user/get" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123456789012345678"
  }'

Example response

JSON

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "coins": 12.5,
    "transactions": [
      {
        "user_id": "123456789012345678",
        "history": "[+2] Daily Rewards",
        "date": "2026-09-27T10:12:31.000Z"
      },
      {
        "user_id": "123456789012345678",
        "history": "[+0.75] Joining Discord Server.",
        "date": "2026-09-26T18:40:02.000Z"
      }
    ],
    "owner": false
  }
}

Response fields

Field	Type	Description
`data.id`	string	Discord ID of the user.
`data.coins`	number	Current coin balance.
`data.transactions`	array	Last 20 transactions, newest first: { user_id, history, date }.
`data.owner`	boolean	true when user_id is the owner of the API key.

If the user has no Join4Join account yet, it is created on the fly and affiliated to you (the Discord ID must belong to a real, non-bot account).

Possible error messages (2)

Missing user_id params in the body.
This user doesn't exist.

Earning coins

List servers to join

POST /api/v1/join4join/farm

Returns the IDs of the promoted servers (invite mode) this user can join right now. The list already takes their alt status, their language and the servers they joined before into account.

Body parameters

Field	Type	Description
`user_id` required	string	Discord ID of the user.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/join4join/farm" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123456789012345678"
  }'

Example response

JSON

{
  "success": true,
  "data": [
    "112233445566778899",
    "223344556677889900"
  ]
}

Response fields

Field	Type	Description
`data`	string[]	Server IDs. Use join4join/info to get their name, icon and invite link.

After joining, the user opens https://join4join.xyz/claim (logged in with Discord) to have the new joins verified. Each verified join credits 0.75 coins.

Joined servers must be kept at least 4 days, otherwise a penalty is deducted. Use join4join/check before letting a user leave.

If the user has no Join4Join account yet, it is created on the fly and affiliated to you (the Discord ID must belong to a real, non-bot account).

Possible error messages (2)

Missing user_id params in the body.
This user doesn't exist.

Server info

POST /api/v1/join4join/info

Returns the public information of a server and the state of its campaign.

Body parameters

Field	Type	Description
`guild_id` required	string	Discord ID of the server.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/join4join/info" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guild_id": "112233445566778899"
  }'

Example response

Response (campaign running)

{
  "success": true,
  "data": {
    "id": "112233445566778899",
    "name": "Indie Game Devs",
    "icon": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "invite": "https://discord.gg/example",
    "ad": "yes",
    "invitation_request": 100,
    "invitation_update": 42,
    "filter_alts": false,
    "filter_lang": "all"
  }
}

Response (no campaign)

{
  "success": true,
  "data": {
    "id": "112233445566778899",
    "ad": "no"
  }
}

Response fields

Field	Type	Description
`data.id`	string	Server ID.
`data.name`	string	Server name.
`data.icon`	string	Icon hash ("0" when none): https://cdn.discordapp.com/icons/{id}/{icon}.png
`data.invite`	string	Invite link of the server.
`data.ad`	"yes" \| "no"	"yes" while a campaign is running.
`data.invitation_request`	number	Members requested when the campaign started.
`data.invitation_update`	number	Members still to be delivered.
`data.filter_alts`	boolean	Alt account filter (only while a campaign is running).
`data.filter_lang`	string	Target language: all, en, fr or tr (only while a campaign is running).

Possible error messages (1)

Missing guild_id params in the body.

Check a server

POST /api/v1/join4join/check

Tells whether a user can leave a server without penalty (they joined it through Join4Join more than 4 days ago, or not through Join4Join at all).

Body parameters

Field	Type	Description
`user_id` required	string	Discord ID of the user.
`guild_id` required	string	Discord ID of the server.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/join4join/check" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123456789012345678",
    "guild_id": "112233445566778899"
  }'

Example response

JSON

{
  "success": true,
  "data": {
    "check": true
  }
}

Response fields

Field	Type	Description
`data.check`	boolean	true when the user can leave the server without penalty.

If the user has no Join4Join account yet, it is created on the fly and affiliated to you (the Discord ID must belong to a real, non-bot account).

Possible error messages (3)

Missing user_id params in the body.
Missing guild_id params in the body.
This user doesn't exist.

Leavable servers

POST /api/v1/join4join/check/all

Lists every server the user joined through Join4Join more than 4 days ago, which they can now leave without penalty.

Body parameters

Field	Type	Description
`user_id` required	string	Discord ID of the user.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/join4join/check/all" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123456789012345678"
  }'

Example response

JSON

{
  "success": true,
  "data": {
    "check": [
      "112233445566778899",
      "223344556677889900"
    ]
  }
}

Response fields

Field	Type	Description
`data.check`	string[]	IDs of the servers that can be left without penalty.

If the user has no Join4Join account yet, it is created on the fly and affiliated to you (the Discord ID must belong to a real, non-bot account).

Possible error messages (2)

Missing user_id params in the body.
This user doesn't exist.

Daily reward

POST /api/v1/join4join/daily

Claims the daily reward of a user when it is available. The base reward is 2 coins, +1 every 3 consecutive days, up to +3.

Body parameters

Field	Type	Description
`user_id` required	string	Discord ID of the user.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/join4join/daily" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123456789012345678"
  }'

Example response

Response (claimed)

{
  "success": true,
  "data": {
    "amount": 2,
    "ready": true,
    "remaining_time": 86400000
  }
}

Response (not ready yet)

{
  "success": true,
  "data": {
    "amount": 3,
    "ready": false,
    "remaining_time": 5400000
  }
}

Response fields

Field	Type	Description
`data.ready`	boolean	true when this call claimed the reward.
`data.amount`	number	Coins credited, or the amount of the next claim when not ready.
`data.remaining_time`	number	Milliseconds until the next claim.

The streak is lost when the previous claim is more than 48 hours old.

If the user has no Join4Join account yet, it is created on the fly and affiliated to you (the Discord ID must belong to a real, non-bot account).

Possible error messages (2)

Missing user_id params in the body.
This user doesn't exist.

Campaigns & coins

Create a campaign

POST /api/v1/join4join/buy

Promotes a server with the coins of a user. Campaigns created through the API use invite mode.

Body parameters

Field	Type	Description
`user_id` required	string	Discord ID of the user who pays.
`coins` required	integer	Coins to spend (minimum 3).
`invite` required	string	Invite link (or code) of the server to promote. Use a permanent invite.
`filter_language` optional	string	Target language: all (default), en, fr or tr.
`filter_account` optional	boolean	true to exclude alt accounts. Default false.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/join4join/buy" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123456789012345678",
    "coins": 100,
    "invite": "https://discord.gg/example",
    "filter_language": "en",
    "filter_account": true
  }'

Example response

Response (confirmation needed)

{
  "success": true,
  "link": "https://join4join.xyz/purchase/aB3dE5gH"
}

Response (user_id is the key owner)

{
  "success": true,
  "link": "https://join4join.xyz/dashboard/promote/112233445566778899"
}

Response fields

Field	Type	Description
`link`	string	Confirmation link, or the campaign page when it started immediately.

When user_id is not the owner of the API key, nothing is charged yet: send the link to the user, who confirms (or cancels) the campaign on the website while logged in. The campaign starts right away only when user_id is your own account.

Each filter reduces the number of members requested by 22%. Only one confirmation can be pending per user and server: a new request replaces the previous one.

Possible error messages (12)

Missing user_id params in the body.
Missing coins params in the body.
coins params should be an int.
Missing invite params in the body.
Please provide a valid language (en,tr,fr,all).
The filter params should be true or false
This user doesn't exist.
The user don't have enough coins.
Please buy at least an ad with 3 coins minimum.
Please provide a valid invite.
Not enough coins for the selected filters.
An ad is already running.

Transfer coins

POST /api/v1/join4join/pay

Sends coins from one user to another.

Body parameters

Field	Type	Description
`user_donator` required	string	Discord ID of the user who sends the coins.
`user_receiver` required	string	Discord ID of the user who receives the coins.
`coins` required	integer	Amount to send (greater than 0).

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/join4join/pay" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_donator": "123456789012345678",
    "user_receiver": "987654321098765432",
    "coins": 50
  }'

Example response

Response (confirmation needed)

{
  "success": true,
  "link": "https://join4join.xyz/transfer/Xy7Kp2Qm"
}

Response (user_donator is the key owner)

{
  "success": true,
  "link": "https://join4join.xyz/dashboard/history"
}

Response fields

Field	Type	Description
`link`	string	Confirmation link, or the history page when the transfer was made immediately.

When user_donator is not the owner of the API key, the sender must open the link while logged in and confirm the transfer. Transfers are final once confirmed.

Possible error messages (9)

Missing user_donator params in the body.
Missing user_receiver params in the body.
Missing coins params in the body.
coins params should be an int.
coins params should be > 0.
user_donator doesn't exist.
user_receiver doesn't exist.
user_donator and user_receiver must be different.
The user don't have enough coins.

Developer

Developer stats

POST /api/v1/developer/stats

Your own numbers as a developer: balance, affiliated users, their joins and your API usage. The API key identifies you, no body is needed.

Body parameters

No body needed: the Authorization header identifies you.

Example request

cURL

curl -X POST "https://join4join.xyz/api/v1/developer/stats" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example response

JSON

{
  "success": true,
  "data": {
    "balance": 1520.4,
    "affiliated_users": 830,
    "affiliated_users_30d": 64,
    "affiliation_farms": 5210,
    "affiliation_earned": 521,
    "api_requests_total": 48210,
    "api_requests_30d": 3920
  }
}

Response fields

Field	Type	Description
`data.balance`	number	Your current coin balance.
`data.affiliated_users`	number	Users affiliated to you (API key and referrals).
`data.affiliated_users_30d`	number	New affiliated users in the last 30 days.
`data.affiliation_farms`	number	Joins made by your affiliated users.
`data.affiliation_earned`	number	Coins earned from those joins (0.1 per join).
`data.api_requests_total`	number	Requests made with your key, all time.
`data.api_requests_30d`	number	Requests made with your key in the last 30 days.

Need help with the API?

Join our Discord server for API support, bug reports and to share what you are building.

Join the support server

Introduction

Get your key

Send POST requests

Earn from your users

Authentication

Responses & limits

Developer rewards

Community bots

Users

Create a user

Body parameters

Example request

Example response

Response fields

Get a user

Body parameters

Example request

Example response

Response fields

Earning coins

List servers to join

Body parameters

Example request

Example response

Response fields

Server info

Body parameters

Example request

Example response

Response fields

Check a server

Body parameters

Example request

Example response

Response fields

Leavable servers

Body parameters

Example request

Example response

Response fields

Daily reward

Body parameters

Example request

Example response

Response fields

Campaigns & coins

Create a campaign

Body parameters

Example request

Example response

Response fields

Transfer coins

Body parameters

Example request

Example response

Response fields

Developer

Developer stats

Body parameters

Example request

Example response

Response fields

Need help with the API?