Ultrareach360 API

RESTful API for Ultrareach360 platform integration

Authentication Endpoint

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:

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

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 token. Please include 'Authorization: Bearer <token>' header."
}

401 Unauthorized:

{
  "success": false,
  "error": "Token has expired. Please login again."
}

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:

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

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 token. Please include 'Authorization: Bearer <token>' header."
}

401 Unauthorized:

{
  "success": false,
  "error": "Token has expired. Please login again."
}

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
The JWT token expires in 7 days
Messaging endpoints require authentication - include the JWT token in the Authorization header
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