API Introduction

The Netasampark REST API provides programmatic access to all platform features. Built with Laravel 11, it offers enterprise-grade performance, security, and scalability.

Base URLs

Production:  https://api.netasampark.com/api
Staging:     https://staging-api.netasampark.com/api
Development: http://localhost:8000/api

API Versioning

The API uses URL-based versioning:

/api/v1/endpoint
/api/v2/endpoint

Current version: v1 (default, version prefix optional)

Authentication

All protected endpoints require Bearer token authentication.

Get Access Token

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com",
      "role": "politician"
    },
    "access_token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer"
  }
}

Using the Token

Include the token in the Authorization header:

Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate Limiting

API endpoints are rate-limited to prevent abuse:

Endpoint Type	Limit	Window
Public endpoints	60 requests	per minute
Authenticated endpoints	120 requests	per minute
Authentication endpoints	5 requests	per minute
OTP endpoints	3 requests	per minute

Rate limit headers are included in responses:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Remaining requests in current window

When rate limit is exceeded, a 429 Too Many Requests response is returned.

Response Format

Success Response

{
  "success": true,
  "message": "Operation successful",
  "data": {
    // Response data
  }
}

Error Response

{
  "success": false,
  "error_code": "error_code",
  "message": "Error message",
  "details": {
    // Additional error details
  }
}

Error Codes

Code	HTTP Status	Description
validation_error	422	Validation failed
unauthorized	401	Authentication required
forbidden	403	Insufficient permissions
not_found	404	Resource not found
rate_limit_exceeded	429	Too many requests
server_error	500	Internal server error

Core Endpoints

Health Check

GET /api/healthz

Authentication

• POST /api/auth/login - Login
• POST /api/auth/register - Register
• POST /api/auth/send-otp - Send OTP
• POST /api/auth/verify-otp - Verify OTP

Voters

• GET /api/voters - List voters
• POST /api/voters - Create voter
• GET /api/voters/{id} - Get voter
• PUT /api/voters/{id} - Update voter
• DELETE /api/voters/{id} - Delete voter

Messaging

• POST /api/messages/send - Send message
• POST /api/messages/broadcast - Broadcast message
• GET /api/messages/history - Message history

Campaigns

• GET /api/campaigns - List campaigns
• POST /api/campaigns - Create campaign
• GET /api/campaigns/{id} - Get campaign

Grievances

• GET /api/grievances - List grievances
• POST /api/grievances - Create grievance
• GET /api/grievances/{id} - Get grievance

Webhooks

The API supports webhooks for real-time event notifications.

Available Events:

• message.delivered
• message.failed
• grievance.created
• grievance.resolved
• payment.processed

SDK Support

SDK configurations are available for:

• JavaScript/TypeScript
• Python
• PHP
• Java

Best Practices

1. Always use HTTPS in production
2. Store tokens securely - Never expose in client-side code
3. Handle errors gracefully - Check for success field
4. Respect rate limits - Implement exponential backoff
5. Use pagination - For large datasets
6. Validate input - Always validate before sending
7. Handle token expiration - Implement refresh logic

Next Steps

• Authentication Guide
• API Endpoints
• Webhooks
• Error Handling

---

Ready to integrate? Check out the API Examples or SDK Documentation