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
9	GET	`/api/v1/admin/users/{userId}`	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
  }
}

9. Admin — Get User by ID

Returns a single user's profile alongside their paginated messages, with optional date range filtering on messages.

Endpoint:

GET /api/v1/admin/users/{userId}

Auth: Required — JWT Bearer token

Path Param:

Param	Type	Description
`userId`	`uuid`	The UUID of the user

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 messages by creation date start
`to`	`yyyy-MM-dd`	No	—	Filter messages by creation date end

Request:

curl "https://somatechapi.nexgate.co/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000?page=0&size=20&from=2024-01-01&to=2024-03-01" \
  -H "Authorization: Bearer <your_access_token>"

Response (200 OK):

{
  "status": "success",
  "message": "User fetched successfully",
  "data": {
    "user": {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+255712345678",
      "connects": 10,
      "createdDate": "2024-01-01T10:00:00Z",
      "totalMessages": 42
    },
    "messages": {
      "content": [
        {
          "messageId": "550e8400-e29b-41d4-a716-446655440002",
          "senderId": "550e8400-e29b-41d4-a716-446655440000",
          "senderName": "John Doe",
          "senderPhone": "+255712345678",
          "text": "Hello",
          "response": "AI response here",
          "recipientPhone": "+255787654321",
          "creationDate": "2024-01-01T10:00:00Z"
        }
      ],
      "totalElements": 42,
      "totalPages": 3,
      "page": 0,
      "size": 20
    }
  }
}

Response (404 Not Found):

{
  "status": "failed",
  "message": "User not found",
  "data": null
}

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

Revision #4
Created 23 March 2026 10:57:44 by Admin Qbit
Updated 21 April 2026 08:34:49 by Admin Qbit