OnSefy Docs

Http Request Format

To validate a user using OnSefy, send a POST request to the /validate/user endpoint with a JSON body. All requests must include the appropriate headers and follow the required field structure.

  • Base URL (Free Version): https://free-api.onsefy.com
  • Base URL (Paid Version): https://api.onsefy.com

🔹Required Headers

HeaderValueRequiredDescription
AuthorizationBearer YOUR_API_KEY✅Your API key as a Bearer token
X-Service-IDYOUR_SERVICE_ID✅The unique ID of your OnSefy application
Content-Typeapplication/json✅Must be set to JSON

Need help with the values? Check out the Obtain your API key & Service ID section.

🔹JSON Request Body

FieldTypeRequiredDescription
emailstring⚪Required if phone is not present. Email address to validate
phonestring⚪Required if email is not present. Phone number (with country code) +15551234567
ipstring✅User’s IP address
namestring✅Full name to check
user_agentstring✅Browser/User-Agent string
vpn_checkboolean❌Enable/disable VPN/proxy detection (optional) (default: false) - paid users only
advancedboolean❌Enable advanced processing (optional) (default: false) - paid users only

🔹Request Format Examples

Example Source Codes

You can check the GitHub Repo user verification api examples here.

GitHub

https://github.com/onsefy/user-verification-api-examples

cURL

If your language example is not listed and need help with integration in your language? You can convert the cURL request to any target language.

For Paid Users Endpoint is

POST https://api.onsefy.com/v1/validate/user

For Free Users Endpoint

POST https://free-api.onsefy.com/v1/validate/user
#!/bin/bash

plan_type="free"  # or "paid"

if [ "$plan_type" == "paid" ]; then
    api_base_uri="https://api.onsefy.com"
else
    api_base_uri="https://free-api.onsefy.com"
fi

bearer_token="your-bearer-token-here"

# Prepare data in JSON format
data='{
    "phone": "+13434129782",
    "email": "test@tempmail.com",
    "ip": "23.27.110.12",
    "name": "John Doe",
    "user_agent": "mozilla/5.0 (macintosh; intel mac os x 10.15; rv:136.0) gecko/20100101 firefox/136.0"
}'
#Avoid this section to speed up the process
#if [ "$plan_type" == "paid" ]; then
    # Add optional fields for paid plan
    #data=$(echo "$data" | sed 's/}/, "vpn_check": true, "advanced": true }/')
#fi

# Send the POST request
response=$(curl -s -X POST "$api_base_uri/v1/validate/user" \
  -H "Authorization: Bearer $bearer_token" \
  -H "X-Service-Id: 04121PSg1744459325" \
  -H "Content-Type: application/json" \
  -d "$data")

# Output the response (raw)
echo "Response: $response"

Node.js (Axios)

npm install axios
const axios = require('axios');

const planType = 'free'; // or 'paid'

const apiBaseUri = planType === 'paid' ? 'https://api.onsefy.com' : 'https://free-api.onsefy.com';
const hostHeader = new URL(apiBaseUri).hostname;

const bearerToken = 'your-bearer-token-here';

let data = {
    phone: '+13434129782',
    email: 'test@tempmail.com',
    ip: '23.27.110.12',
    name: 'John Doe',
    user_agent: 'mozilla/5.0 (macintosh; intel mac os x 10.15; rv:136.0) gecko/20100101 firefox/136.0'
};
/* Avoid this section to speed up the process
if (planType === 'paid') {
    data.vpn_check = true;
    data.advanced = true;
}
*/
const headers = {
    'Authorization': `Bearer ${bearerToken}`,
    'X-Service-Id': '04121PSg1744459325',
    'Host': hostHeader,
    'Content-Type': 'application/json',
};

async function validateUser() {
    try {
        const response = await axios.post(`${apiBaseUri}/v1/validate/user`, data, { headers });
        const result = response.data;

        if (result && result.transaction_id) {
            console.log("Transaction ID (from API):", result.transaction_id || 'N/A');
            console.log("Result Summary:", JSON.stringify(result.summary, null, 2));
            console.log("Response:", JSON.stringify(result, null, 2));
        } else {
            console.log("Response:", JSON.stringify(result, null, 2));
        }
    } catch (error) {
        console.error("Request failed:", error.message);
    }
}

validateUser();

PHP (cURL)

Request Example (PHP Guzzle)

Install Guzzle

composer require guzzlehttp/guzzle
<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$planType = 'free'; // or 'paid'

$apiBaseUri = $planType === 'paid' ? 'https://api.onsefy.com' : 'https://free-api.onsefy.com';
$hostHeader = parse_url($apiBaseUri, PHP_URL_HOST);

$client = new Client([
    'base_uri' => $apiBaseUri,
    'timeout'  => 5.0,
]);

$bearerToken = 'your-bearer-token-here';

$data = [
    'phone' => '+13434129782',
    'email' => 'test@tempmail.com',
    'ip' => '23.27.110.12',
    'name' => 'John Doe',
    'user_agent' => 'mozilla/5.0 (macintosh; intel mac os x 10.15; rv:136.0) gecko/20100101 firefox/136.0'
];

/* Avoid this section to speed up the process
if ($planType === 'paid') {
   $data['vpn_check'] = true;
   $data['advanced'] = true;
}
*/

$headers = [
    'Authorization' => 'Bearer ' . $bearerToken,
    'X-Service-Id'  => '04121PSg1744459325',
    'Host'          => $hostHeader,
    'Content-Type'  => 'application/json',
];

try {
    $response = $client->post('/v1/validate/user', [
        'headers' => $headers,
        'json' => $data,
    ]);

    $body = $response->getBody();
    $result = json_decode($body, true);
    
    if($result and isset($result['transaction_id'])) {
        echo "Transaction ID (from API): " . ($result['transaction_id'] ?? 'N/A') . PHP_EOL;
        echo "Result Summary: " . json_encode($result['summary'], JSON_PRETTY_PRINT) . PHP_EOL;
        echo "Response: " . json_encode($result, JSON_PRETTY_PRINT) . PHP_EOL;
    } else {
        echo "Response: " . json_encode($result, JSON_PRETTY_PRINT) . PHP_EOL;
    }

} catch (\GuzzleHttp\Exception\RequestException $e) {
    echo "Request failed: " . $e->getMessage();
}

Python (requests)

import requests
from urllib.parse import urlparse

plan_type = 'free'  # or 'paid'

api_base_uri = 'https://api.onsefy.com' if plan_type == 'paid' else 'https://free-api.onsefy.com'
host_header = urlparse(api_base_uri).hostname

bearer_token = 'your-bearer-token-here'

data = {
    'phone': '+13434129782',
    'email': 'test@tempmail.com',
    'ip': '23.27.110.12',
    'name': 'John Doe',
    'user_agent': 'mozilla/5.0 (macintosh; intel mac os x 10.15; rv:136.0) gecko/20100101 firefox/136.0'
}

# Avoid this section to speed up the process
#if plan_type == 'paid':
#    data['vpn_check'] = True
#    data['advanced'] = True

headers = {
    'Authorization': f'Bearer {bearer_token}',
    'X-Service-Id': '04121PSg1744459325',
    'Host': host_header,
    'Content-Type': 'application/json',
}

try:
    response = requests.post(f'{api_base_uri}/v1/validate/user', json=data, headers=headers, timeout=5)
    response.raise_for_status()
    result = response.json()

    if result and 'transaction_id' in result:
        print("Transaction ID (from API):", result.get('transaction_id', 'N/A'))
        print("Result Summary:", result.get('summary', {}))
        print("Response:", result)
    else:
        print("Response:", result)

except requests.exceptions.RequestException as e:
    print("Request failed:", str(e))

🔹Best Practices

  • Always use HTTPS to keep data secure
  • Strip whitespace and sanitize input fields before sending
  • Store and rotate API keys securely (avoid exposing in frontend)

If your language example is not listed and need help with integration in your language? You can convert the cURL request to any language.

GitHub

https://github.com/onsefy/user-verification-api-examples

Prev
API Key Usage
Next
Post Data Formatting