API v1

Social TikTok Lookup API

Search TikTok users and retrieve balance. Authentication via token from Telegram bot.

Authentication

Every request must include a valid token issued by the Telegram bot. To get your token and top up balance:

Open Telegram and go to @socialfinderbot_bot
Click "Get API Token" to receive your token.
Click "Add your balance" to top up credits (balance).

Tokens are tied to user accounts. Inactive or invalid tokens return errors. Make sure your account is active and has sufficient balance.

Base URL & Headers

Our API's base URL is:
https://socialfinder.net/api/index.php?v=1

Content-Type: application/json

No additional auth headers—just JSON body including action and token.

Request example payload:

{
  "action":"searchTiktok",
  "token":"your_token_here",
  "text":"@username_or_phone"
}

Endpoints

POST

searchTiktok

Searches TikTok data by provided text (username/phone/etc.). It will normalize input by stripping ( ) + - / @ characters.

Request Body

Field	Type	Required	Description
`action`	string	yes	Must be `searchTiktok`
`token`	string	yes	API token from Telegram bot
`text`	string	yes	Search string (username, phone, etc.)—will be sanitized

Success Response

{
  "status":"success",
  "message":"User found",
  "data": { /* result from Functions::getTiktokData */ }
}

Failure Responses

{
  "status":"error",
  "message":"User not found"
}

{
  "status":"error",
  "message":"Your balance is not enough"
}

{
  "status":"error",
  "message":"Token is not valid"
}

Side Effects

Decrements user balance by 1 on success.

Example cURL

curl -X POST https://socialfinder.net/api/index.php?v=1 \
  -H "Content-Type: application/json" \
  -d '{
    "action":"searchTiktok",
    "token":"REPLACE_WITH_TOKEN",
    "text":"@someuser"
  }'

Example JavaScript (fetch)

fetch("https://socialfinder.net/api/index.php?v=1", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "searchTiktok",
    token: "REPLACE_WITH_TOKEN",
    text: "@someuser"
  })
})
.then(r => r.json())
.then(console.log)
.catch(console.error);

POST

getBalance

Returns current user's balance.

Request Body

Field	Type	Required	Description
`action`	string	yes	Must be `getBalance`
`token`	string	yes	API token

Success Response

{
  "status":"success",
  "message":"Balance retrieved",
  "data": {
    "balance": 42
  }
}

Error Responses

{
  "status":"error",
  "message":"Token is not valid"
}

{
  "status":"error",
  "message":"Your account is not active"
}

Example cURL

curl -X POST https://socialfinder.net/api/index.php?v=1 \
  -H "Content-Type: application/json" \
  -d '{
    "action":"getBalance",
    "token":"REPLACE_WITH_TOKEN"
  }'

POST

Invalid action

If action is unrecognized:

{
  "status":"error",
  "message":"Invalid action"
}

Errors & Troubleshooting

Common error cases

Invalid token: Token missing or wrong. Check the token from Telegram bot.
Inactive account: User exists but active != 1. Contact with support.
Insufficient balance: For searchTiktok, balance must be > 0.
Malformed JSON: API expects valid JSON. Return will be parsing error from client side if invalid.

Best practices

Always trim & sanitize text before showing or logging.
Use HTTPS to protect token leak.
Implement client-side exponential retry for transient failures (e.g., network issues) but avoid double-charging balance (idempotency if needed).
Rate-limit per user on your side if abuse observed.

Currently all responses are 200 with status inside JSON—document this so integrators aren’t confused.