v1.0
Base URL: /api ⚡ Swagger UI 🚀 Open Simulator
Vivekam REST API — Developer Guide

Complete reference for integrating with the Vivekam financial platform. All endpoints require authentication using a session token obtained via the POST /api/auth/login endpoint.

🔑
9
Auth Endpoints
📊
113
VTP Endpoints
💹
137
Price Endpoints
📧
8
Order Mail Endpoints
🤝
33
Partner Products
🚀
300
Total Endpoints

Base URLs

EnvironmentBase URLUsage
LOCALhttp://localhost:PORT/apiDevelopment / Local testing
TESThttp://vivekamih.gotdns.com:8033/apiInternal testing
PRODhttp://183.82.48.178:8033/apiProduction (external access)

Request Format

  • All requests and responses are JSON
  • Set header: Content-Type: application/json
  • Set header: Accept: application/json
  • Authenticated requests must include: X-Session-Token: <your-token>
  • Dates use ISO 8601 format: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss
Authentication

All API endpoints (except login, register, forgot-password, reset-password) require a valid session token. Sessions expire after 8 hours of inactivity and auto-renew on each use.

Session Token Flow: Login → receive sessionToken → send as X-Session-Token header on every request → re-login if you receive HTTP 401.

Step-by-Step Integration Guide

1

Register an account (first time only)

Contact your Vivekam administrator to create an account, or call POST /api/auth/register if self-registration is enabled.

2

Login to get a Session Token

Call POST /api/auth/login with your credentials. Save the sessionToken from the response.

3

Include token in every API request

Add the header X-Session-Token: <your-sessionToken> to every request.

4

Handle 401 Unauthorized responses

If you receive HTTP 401, your session has expired. Call login again to get a new token and retry the request.

Login Example

cURL C# JavaScript Python
# 1. Login and get session token
curl -X POST http://vivekamih.gotdns.com:8033/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@123"}'

# 2. Use the token in subsequent requests
curl http://vivekamih.gotdns.com:8033/api/vtp/member-ledger?memberId=101 \
  -H "X-Session-Token: <your-session-token>"
using System.Net.Http;
using Newtonsoft.Json;

var client = new HttpClient();
client.BaseAddress = new Uri("http://vivekamih.gotdns.com:8033/api/");

// 1. Login
var loginBody = JsonConvert.SerializeObject(new { username="admin", password="Admin@123" });
var res = await client.PostAsync("auth/login",
    new StringContent(loginBody, Encoding.UTF8, "application/json"));

dynamic data = JsonConvert.DeserializeObject(await res.Content.ReadAsStringAsync());
string token = data.sessionToken;

// 2. Use token
client.DefaultRequestHeaders.Add("X-Session-Token", token);
var ledger = await client.GetAsync("vtp/member-ledger?memberId=101");
// 1. Login
const res = await fetch('http://vivekamih.gotdns.com:8033/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'admin', password: 'Admin@123' })
});
const { sessionToken } = await res.json();
localStorage.setItem('vtp_token', sessionToken);

// 2. Make authenticated requests
const ledger = await fetch('http://vivekamih.gotdns.com:8033/api/vtp/member-ledger?memberId=101', {
  headers: { 'X-Session-Token': sessionToken }
});
const data = await ledger.json();
import requests

BASE = "http://vivekamih.gotdns.com:8033/api"

# 1. Login
r = requests.post(f"{BASE}/auth/login",
    json={"username": "admin", "password": "Admin@123"})
token = r.json()["sessionToken"]
headers = {"X-Session-Token": token}

# 2. Make authenticated requests
ledger = requests.get(f"{BASE}/vtp/member-ledger",
    params={"memberId": 101}, headers=headers)
print(ledger.json())

Password Rules

  • Minimum 8 characters
  • At least one uppercase letter (A–Z)
  • At least one digit (0–9)
  • At least one special character: @ # $ ! % * ? &
Account Lockout: After 5 consecutive failed login attempts, the account is locked for 30 minutes. Use forgot-password to reset.
🔑

Auth Controller 9 endpoints

User management, login, session and password operations — Base route: /api/auth

📊

VTP Controller 113 endpoints

Portfolio management, billing, member ledger, orders and more — Base route: /api/vtp

💹

Price Controller 137 endpoints

Market data, scrip details, AIMS, PIE, PRIMER, mutual funds — Base route: /api/price

📧

Order Mail Controller 8 endpoints

Trading order mail operations — Base route: /api/ordermail

🤝

Partner Products Controller 33 endpoints

Portfolio baskets, instruments, blocking periods, rebalance — Base route: /api/partnerproducts

Error Codes & Responses

All errors return JSON — never HTML. Every error response includes success: false and a message field.

HTTP CodeMeaningExample ResponseAction
200 OKSuccess{"success":true,"data":…}Process the response data
400 Bad RequestMissing or invalid parameters{"success":false,"message":"Username required"}Check request body / query params
401 UnauthorizedMissing or expired session token{"success":false,"message":"Session expired…","loginUrl":"…"}Re-login and retry
403 ForbiddenInsufficient role (e.g. Admin required){"success":false,"message":"Admin role required"}Use an account with Admin role
404 Not FoundResource not found{"success":false,"message":"Record not found"}Verify the request parameters
500 Server ErrorUnexpected server error{"success":false,"error":"…","message":"…"}Contact support with the error details

Standard Error Response Structure

{
  "success":      false,
  "status":       401,
  "error":        "Unauthorized",
  "message":      "Session expired. Please login again.",
  "loginUrl":     "http://server/api/auth/login",
  "timestamp":    "2026-03-19 10:30:00"
}
Client SDKs & Sample Code

Ready-to-use client libraries are available for common platforms. All clients handle login, session renewal, and automatic re-authentication on 401.

⚙️

C# Client

Full async client with auto token refresh for .NET 4.5+

Download .cs
🌐

JavaScript Client

Browser & Node.js compatible ES6 class

Download .js
🐍

Python Client

Python 3 client using requests library

Download .py
🚀

Live Simulator

Test all 300 endpoints interactively in your browser

Open Simulator
💻

cURL Examples

Ready-to-run cURL command examples for all operations

Download .sh