Skip to main content

SomaTech Stats API

Base URL: https://somatechapi.nexgate.co

Endpoint Overview

# Method Path Auth Required
1 GET /api/v1/stats No
2 GET /api/v1/stats/trend No
3 POST /api/v1/auth/add No
4 POST /api/v1/auth/request-otp No
5 POST /api/v1/auth/verify-otp No
6 POST /api/v1/message/send Yes — JWT
7 GET /api/v1/admin/users Yes — JWT
8 GET /api/v1/admin/messages Yes — JWT

Public Endpoints

1. Overall Stats

Returns total counts with no date filtering.

Endpoint:

GET /api/v1/stats

Auth: None — public endpoint

Request:

curl https://somatechapi.nexgate.co/api/v1/stats

Response:

{
  "status": "success",
  "message": "Stats fetched successfully",
  "data": {
    "totalUsers": 1500,
    "totalMessages": 12400,
    "totalResponses": 11800,
    "trend": null
  }
}

2. Trend Stats

Returns overall counts plus daily breakdown for a date range.

Endpoint:

GET /api/v1/stats/trend

Auth: None — public endpoint

Query Params:

Param Type Required Description
from yyyy-MM-dd No Start date. Defaults to 30 days ago
to yyyy-MM-dd No End date. Defaults to today

Request:

# With date range
curl "https://somatechapi.nexgate.co/api/v1/stats/trend?from=2024-01-01&to=2024-03-01"

# Default last 30 days
curl "https://somatechapi.nexgate.co/api/v1/stats/trend"

Response:

{
  "status": "success",
  "message": "Stats fetched successfully",
  "data": {
    "totalUsers": 1500,
    "totalMessages": 12400,
    "totalResponses": 11800,
    "trend": [
      {
        "date": "2024-01-01",
        "messages": 120,
        "responses": 115,
        "newUsers": 30
      },
      {
        "date": "2024-01-02",
        "messages": 98,
        "responses": 95,
        "newUsers": 12
      }
    ]
  }
}

Protected Endpoints

These endpoints require a valid JWT token in the Authorization header.

Authorization: Bearer <your_access_token>

6. Send Message

Sends an SMS message on behalf of the authenticated server.

Endpoint:

POST /api/v1/message/send

Auth: Required — JWT Bearer token

Request Body:

Field Type Required Description
phoneNumber string Yes Recipient phone number
text string Yes Message content
sender uuid No Sender UUID 
{
  "phoneNumber": "+255712345678",
  "text": "Hello from SMS Gateway"
}

Request:

curl -X POST https://somatechapi.nexgate.co/api/v1/message/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{"phoneNumber": "+255712345678", "text": "Hello from SMS Gateway"}'

Response:

{
  "status": "success",
  "message": "Message sent successfully",
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "sender": "550e8400-e29b-41d4-a716-446655440001",
    "phoneNumber": "+255712345678",
    "text": "Hello from SMS Gateway",
    "response": "AI response here",
    "creationDate": "2024-01-01T10:00:00Z",
    "modificationDate": "2024-01-01T10:00:00Z",
    "isDeleted": false
  }
}

7. Admin — List Users

Returns a paginated list of all registered users with optional date filtering.

Endpoint:

GET /api/v1/admin/users

Auth: Required — JWT Bearer token

Query Params:

Param Type Required Default Description
page int No 0 Page number (zero-based)
size int No 20 Page size
from yyyy-MM-dd No — Filter by creation date start
to yyyy-MM-dd No — Filter by creation date end

Request:

curl "https://somatechapi.nexgate.co/api/v1/admin/users?page=0&size=20" \
  -H "Authorization: Bearer <your_access_token>"

Response:

{
  "status": "success",
  "message": "Users fetched successfully",
  "data": {
    "content": [
      {
        "userId": "550e8400-e29b-41d4-a716-446655440000",
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumber": "+255712345678",
        "connects": 10,
        "createdDate": "2024-01-01T10:00:00Z",
        "totalMessages": 42
      }
    ],
    "totalElements": 1500,
    "totalPages": 75,
    "page": 0,
    "size": 20
  }
}

8. Admin — List Messages

Returns a paginated list of all messages with optional date filtering.

Endpoint:

GET /api/v1/admin/messages

Auth: Required — JWT Bearer token

Query Params:

Param Type Required Default Description
page int No 0 Page number (zero-based)
size int No 20 Page size
from yyyy-MM-dd No — Filter by creation date start
to yyyy-MM-dd No — Filter by creation date end

Request:

curl "https://somatechapi.nexgate.co/api/v1/admin/messages?page=0&size=20&from=2024-01-01&to=2024-03-01" \
  -H "Authorization: Bearer <your_access_token>"

Response:

{
  "status": "success",
  "message": "Messages fetched successfully",
  "data": {
    "content": [
      {
        "messageId": "550e8400-e29b-41d4-a716-446655440000",
        "senderId": "550e8400-e29b-41d4-a716-446655440001",
        "senderName": "John Doe",
        "senderPhone": "+255712345678",
        "text": "Hello",
        "response": "AI response here",
        "recipientPhone": "+255787654321",
        "creationDate": "2024-01-01T10:00:00Z"
      }
    ],
    "totalElements": 12400,
    "totalPages": 620,
    "page": 0,
    "size": 20
  }
}

Notes

  • All dates must be in yyyy-MM-dd format
  • If from is provided without to, to defaults to today
  • If neither is provided, trend defaults to last 30 days
  • trend is null on the overall stats endpoint
  • JWT tokens are obtained from the /api/v1/auth/verify-otp response
  • Pagination is zero-based — page=0 returns the first page
Back to top