Ultrareach360 API

RESTful API for Ultrareach360 platform integration

Authentication

All messaging endpoints require authentication via the Authorization header. You can authenticate using either a JWT token or your API key directly.

Option 1: API Key (Recommended)

Use your API key directly in the Authorization header. No login step required.

Authorization: Bearer <your-api-key>

Option 2: JWT Token

Authorization: Bearer <your-jwt-token-from-login>

POST/v1/auth/login

Request Body:

{
  "username": "user@example.com",
  "password": "your-password",
  "apiKey": "your-api-key-from-dashboard"
}

Success Response (200):

{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "email": "user@example.com",
    "plan": "professional",
    "role": "user",
    "partner": {
      "id": "507f1f77bcf86cd799439012",
      "name": "Partner Company",
      "email": "partner@example.com"
    }
  }
}

Error Responses:

400 Bad Request:

{
  "success": false,
  "error": "Please provide username, password, and apiKey"
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid credentials"
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid API key"
}

403 Forbidden:

{
  "success": false,
  "error": "API access not approved. Please request API access first.",
  "apiAccessStatus": "pending"
}

Messaging Endpoints

Send Email

POST/v1/messaging/send-emailRequires Authentication

Headers:

// Using API key directly
Authorization: Bearer <your-api-key>

// Or using JWT token from login
Authorization: Bearer <your-jwt-token>

Request Body:

{
  "businessGroup": "The Example Company",
  "to": "john@example.com",
  "subject": "Welcome",
  "body": "Hello John, this is your welcome email."
}

Success Response (200):

{
  "success": true,
  "message": "Email sent successfully",
  "data": {
    "businessGroup": "The Example Company",
    "to": "john@example.com",
    "subject": "[The Example Company] Welcome",
    "sentAt": "2025-11-27T12:00:00.000Z"
  }
}

Error Responses:

401 Unauthorized:

{
  "success": false,
  "error": "Missing authorization. Include 'Authorization: Bearer <token-or-apikey>' header."
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or inactive API key."
}

400 Bad Request:

{
  "success": false,
  "error": "Please provide businessGroup, to, subject, and body"
}

400 Bad Request:

{
  "success": false,
  "error": "Invalid email address format"
}

500 Internal Server Error:

{
  "success": false,
  "error": "Email service is not configured. Please contact administrator."
}

Send SMS

POST/v1/messaging/send-smsRequires Authentication

Headers:

// Using API key directly
Authorization: Bearer <your-api-key>

// Or using JWT token from login
Authorization: Bearer <your-jwt-token>

Request Body:

{
  "businessGroup": "The Example Company",
  "to": "+12345678901",
  "body": "Hello John, this is your welcome message."
}

Success Response (200):

{
  "success": true,
  "message": "SMS sent successfully",
  "data": {
    "businessGroup": "The Example Company",
    "to": "+12345678901",
    "messageId": "SM1234567890abcdef",
    "status": "queued",
    "sentAt": "2025-11-27T12:00:00.000Z",
    "segments": 1
  }
}

Error Responses:

401 Unauthorized:

{
  "success": false,
  "error": "Missing authorization. Include 'Authorization: Bearer <token-or-apikey>' header."
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or inactive API key."
}

400 Bad Request:

{
  "success": false,
  "error": "Please provide businessGroup, to, and body"
}

400 Bad Request:

{
  "success": false,
  "error": "Invalid phone number format. Use E.164 format (e.g., +1234567890)"
}

400 Bad Request:

{
  "success": false,
  "error": "Message body is too long. Maximum length is 1600 characters."
}

500 Internal Server Error:

{
  "success": false,
  "error": "SMS service is not configured. Please contact administrator."
}

Notes:

Users must have API access status set to "approved"
API key is provided in the dashboard after approval
Messaging endpoints accept either an API key or a JWT token via Authorization: Bearer
API key auth requires no login step — use it directly
JWT tokens expire in 7 days and require the login endpoint to obtain
All endpoints use JSON for request and response bodies
Business group name is prefixed to all email subjects and SMS messages
Phone numbers should be in E.164 format (e.g., +1234567890)
SMS messages are limited to 1600 characters