Api Reference

Complete API Reference

This document provides a comprehensive reference for all NotifyHub API endpoints.

Base URL

https://api.notifyhub.com

Authentication Endpoints

POST /auth/signup

Register a new organization and create the first admin user.

Authentication: Not required

Request Body:

{
  "firstName": "string (required)",
  "lastName": "string (required)",
  "email": "string (required, unique)",
  "password": "string (required, min 8 chars)",
  "countryCode": "string (required)",
  "phoneNumber": "string (required)",
  "companyName": "string (required)",
  "sector": "string (required)",
  "country": "string (required)",
  "role": "string (optional, default: 'admin')"
}

Success Response (201):

{
  "token": "string (JWT)",
  "user": { "object" }
}

Error Responses:

  • 400: Email already exists, validation errors

Example:

curl -X POST https://api.notifyhub.com/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"firstName":"John","lastName":"Doe","email":"john@example.com","password":"SecurePass123!","countryCode":"+254","phoneNumber":"712345678","companyName":"Acme","sector":"Tech","country":"Kenya"}'

POST /auth/login

Authenticate and receive a JWT token.

Authentication: Not required

Request Body:

{
  "email": "string (required)",
  "password": "string (required)"
}

Success Response (200):

{
  "token": "string (JWT)",
  "user": { "object" }
}

Error Responses:

  • 401: Invalid credentials

Example:

curl -X POST https://api.notifyhub.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"john@example.com","password":"SecurePass123!"}'

User Management Endpoints

Authentication Requirements

All protected endpoints require one of the following:

  1. Authorization: Bearer <jwt_token> (Header)
  2. UNIFIED-API-Key: <api_key> (Header)
  3. ?apikey=<api_key> (Query Parameter)

GET /users

List all users in your organization.

Authentication: Required (Admin only)

Success Response (200):

[
  {
    "_id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "role": "admin|user",
    "organization": "string (ID)",
    "isActive": "boolean",
    "createdAt": "string (ISO date)",
    "updatedAt": "string (ISO date)"
  }
]

GET /users/me

Get current user's profile.

Authentication: Required

Success Response (200):

{
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "role": "admin|user",
  "organization": {
    "_id": "string",
    "name": "string",
    "sector": "string",
    "country": "string",
    "credits": "number"
  },
  "isActive": "boolean",
  "createdAt": "string",
  "updatedAt": "string"
}

POST /users

Create a new team member.

Authentication: Required (Admin only)

Request Body:

{
  "firstName": "string (required)",
  "lastName": "string (required)",
  "email": "string (required, unique)",
  "password": "string (required)",
  "countryCode": "string (required)",
  "phoneNumber": "string (required)",
  "role": "string (optional, default: 'user')"
}

Success Response (201):

{
  "_id": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "role": "string",
  "organization": "string",
  "isActive": true,
  "createdAt": "string",
  "updatedAt": "string"
}

PUT /users/:id

Update user details.

Authentication: Required (Admin only)

Path Parameters:

  • id: User ID

Request Body (partial update):

{
  "firstName": "string (optional)",
  "lastName": "string (optional)",
  "phoneNumber": "string (optional)",
  "role": "string (optional)"
}

Success Response (200):

{
  "_id": "string",
  "firstName": "string (updated)",
  /* ... other fields ... */
}

PUT /users/:id/deactivate

Deactivate a user account.

Authentication: Required (Admin only)

Success Response (200):

{
  "_id": "string",
  "isActive": false,
  /* ... other fields ... */
}

PUT /users/:id/reactivate

Reactivate a user account.

Authentication: Required (Admin only)

Success Response (200):

{
  "_id": "string",
  "isActive": true,
  /* ... other fields ... */
}

DELETE /users/:id

Permanently delete a user.

Authentication: Required (Admin only)

Success Response (200):

{
  "message": "User Deleted Successfully"
}

PUT /users/:id/password

Change user password.

Authentication: Required

Request Body:

{
  "oldPassword": "string (required for self-change)",
  "newPassword": "string (required)"
}

Success Response (200):

{
  "_id": "string",
  /* ... user object without password ... */
}

Organization Endpoints

GET /organizations/current

Get current organization details and credentials.

Authentication: Required

Success Response (200):

{
  "_id": "string",
  "name": "string",
  "sector": "string",
  "country": "string",
  "credits": "number",
  "emailFromName": "string|null",
  "credentials": {
    "sms_apiUrl": "string",
    "sms_apiKey": "string",
    "sms_partnerID": "string",
    "sms_shortCode": "string",
    "email_host": "string",
    "email_port": "string",
    "email_user": "string",
    "email_pass": "string",
    "email_from": "string"
  },
  "createdAt": "string",
  "updatedAt": "string"
}

PUT /organizations/current/credentials

Update organization-specific channel credentials.

Authentication: Required (Admin only)

Request Body (partial update):

{
  "sms_apiKey": "string (optional)",
  "sms_partnerID": "string (optional)",
  "sms_shortCode": "string (optional)",
  "email_host": "string (optional)",
  "email_port": "string (optional)",
  "email_user": "string (optional)",
  "email_pass": "string (optional)",
  "email_from": "string (optional)",
  "whatsapp_access_token": "string (optional)",
  "whatsapp_phone_number_id": "string (optional)"
}

Success Response (200):

{
  "_id": "string",
  "credentials": {
    /* ... updated credentials ... */
  },
  /* ... other fields ... */
}

Contact Endpoints

POST /contacts

Create a new contact.

Authentication: Required

Request Body:

{
  "name": "string (required)",
  "email": "string (optional)",
  "phone": "string (optional)",
  "countryCode": "string (optional)",
  "organization": "string (optional)",
  "tags": ["array of strings (optional)"],
  "groups": ["array of group IDs (optional)"]
}

Note: At least one of email or phone required.

Success Response (201):

{
  "_id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "countryCode": "string",
  "organization": "string",
  "tags": ["array"],
  "groups": ["array"],
  "NotifyhubOrganization": "string (ID)",
  "createdAt": "string",
  "updatedAt": "string"
}

GET /contacts

List all contacts in your organization.

Authentication: Required

Success Response (200):

[
  {
    "_id": "string",
    "name": "string",
    "email": "string",
    "phone": "string",
    "organization": "string",
    "tags": ["array"],
    "groups": ["array"],
    "createdAt": "string",
    "updatedAt": "string"
  }
]

GET /contacts/:id

Get a specific contact.

Authentication: Required

Path Parameters:

  • id: Contact ID

Success Response (200):

{
  "_id": "string",
  "name": "string",
  /* ... all contact fields ... */
}

PUT /contacts/:id

Update contact details.

Authentication: Required

Path Parameters:

  • id: Contact ID

Request Body (partial update):

{
  "name": "string (optional)",
  "email": "string (optional)",
  "phone": "string (optional)",
  "tags": ["array (optional)"],
  "groups": ["array (optional)"]
}

Success Response (200):

{
  "_id": "string",
  /* ... updated contact ... */
}

DELETE /contacts/:id

Delete a contact permanently.

Authentication: Required

Path Parameters:

  • id: Contact ID

Success Response (200):

{
  "message": "Contact deleted successfully"
}

Group Endpoints

POST /groups

Create a new group.

Authentication: Required

Request Body:

{
  "name": "string (required, unique within org)",
  "description": "string (optional)",
  "color": "string (required, Tailwind classes)"
}

Success Response (201):

{
  "_id": "string",
  "name": "string",
  "description": "string",
  "color": "string",
  "organization": "string (ID)",
  "createdAt": "string",
  "updatedAt": "string"
}

GET /groups

List all groups in your organization.

Authentication: Required

Success Response (200):

[
  {
    "_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "organization": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
]

DELETE /groups/:id

Delete a group permanently.

Authentication: Required

Path Parameters:

  • id: Group ID

Success Response (200):

{
  "message": "Group deleted successfully"
}

Notification Endpoints

POST /notifications/send

Send a notification to one or multiple recipients.

Authentication: Required

Request Body:

{
  "type": "sms|email|whatsapp (required)",
  "to": "string or array (required)",
  "message": "string (required)",
  "subject": "string (required for email)",
  "attachments": ["array (optional, email only)"]
}

Email Attachment Format:

{
  "filename": "string",
  "content": "string (base64)",
  "contentType": "string (MIME type)"
}

Success Response (200) - Single recipient:

{
  "recipient": "string",
  "status": "success"
}

Success Response (200) - Multiple recipients:

[
  {
    "recipient": "string",
    "status": "success|failed",
    "error": "string (if failed)"
  }
]

Examples:

SMS:

curl -X POST https://api.notifyhub.com/notifications/send \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"sms","to":"+254712345678","message":"Hello!"}'

Email:

curl -X POST https://api.notifyhub.com/notifications/send \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"email","to":"user@example.com","subject":"Test","message":"<p>Hello!</p>"}'

WhatsApp:

curl -X POST https://api.notifyhub.com/notifications/send \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"whatsapp","to":"+254712345678","message":"Hello!"}'

POST /notifications/send-to-all

Send a notification to all contacts in your organization.

Authentication: Required

Request Body:

{
  "type": "sms|email|whatsapp (required)",
  "to": "all",
  "message": "string (required)",
  "subject": "string (required for email)"
}

Success Response (200):

[
  {
    "recipient": "string",
    "status": "success|failed",
    "error": "string (if failed)"
  }
]

Campaign Endpoints

POST /campaigns

Create a new campaign.

Authentication: Required

Request Body:

{
  "name": "string (required)",
  "description": "string (optional)",
  "type": "broadcast|targeted|automated|recurring (required)",
  "channels": ["array of: email, sms, whatsapp (required)"],
  "recipients": {
    "contacts": ["array of contact IDs (optional)"],
    "groups": ["array of group IDs (optional)"],
    "manual": ["array of emails/phones (optional)"]
  },
  "messages": {
    "email": {
      "subject": "string (required if email channel)",
      "content": "string (required)"
    },
    "sms": {
      "content": "string (required if sms channel)"
    },
    "whatsapp": {
      "content": "string (required if whatsapp channel)"
    }
  },
  "scheduleDate": "string (ISO 8601, optional)"
}

Success Response (201):

{
  "_id": "string",
  "name": "string",
  "type": "string",
  "channels": ["array"],
  "status": "draft",
  "recipientType": "all|selected|group",
  "selectedContacts": ["array"],
  "selectedGroup": "string",
  "messages": { "object" },
  "scheduleDate": "string|null",
  "analytics": {
    "sent": 0,
    "delivered": 0,
    "failed": 0,
    "opened": 0,
    "clicked": 0
  },
  "organization": "string",
  "createdBy": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

GET /campaigns

List all campaigns in your organization.

Authentication: Required

Success Response (200):

[
  {
    "_id": "string",
    "name": "string",
    "type": "string",
    "status": "draft|scheduled|active|completed|canceled",
    "channels": ["array"],
    "analytics": { "object" },
    "createdAt": "string"
  }
]

GET /campaigns/:id

Get detailed information about a specific campaign.

Authentication: Required

Path Parameters:

  • id: Campaign ID

Success Response (200):

{
  "_id": "string",
  "name": "string",
  "description": "string",
  "type": "string",
  "channels": ["array"],
  "status": "string",
  "recipientType": "string",
  "messages": { "object" },
  "scheduleDate": "string",
  "analytics": { "object" },
  "createdAt": "string",
  "updatedAt": "string"
}

PUT /campaigns/:id

Update campaign details (only for draft/scheduled campaigns).

Authentication: Required

Path Parameters:

  • id: Campaign ID

Request Body (partial update):

{
  "name": "string (optional)",
  "messages": { "object (optional)" },
  "scheduleDate": "string (optional)"
}

Success Response (200):

{
  "_id": "string",
  /* ... updated campaign ... */
}

POST /campaigns/:id/launch

Launch a campaign immediately or schedule it.

Authentication: Required

Path Parameters:

  • id: Campaign ID

Success Response (200):

{
  "_id": "string",
  "status": "active|scheduled|completed",
  "analytics": { "object (if completed)" },
  "updatedAt": "string"
}

POST /campaigns/:id/cancel

Cancel a scheduled or active campaign.

Authentication: Required

Path Parameters:

  • id: Campaign ID

Success Response (200):

{
  "_id": "string",
  "status": "canceled",
  "updatedAt": "string"
}

Message Logs Endpoints

GET /message-logs

Retrieve message history with optional filters.

Authentication: Required

Query Parameters (all optional):

  • channel: Filter by channel (email, sms, whatsapp)
  • status: Filter by status (success, failed)
  • dateFrom: Filter by start date (ISO 8601)
  • dateTo: Filter by end date (ISO 8601)
  • campaignId: Filter by campaign ID

Success Response (200):

[
  {
    "_id": "string",
    "channel": "email|sms|whatsapp",
    "senderUserId": "string",
    "senderOrgId": "string",
    "network": "string",
    "recipients": [
      {
        "recipient": "string",
        "status": "success|failed|pending",
        "error": "string (if failed)"
      }
    ],
    "messagePreview": "string (first 100 chars)",
    "messageLength": "number",
    "cost": "number",
    "campaignId": "string|null",
    "createdAt": "string",
    "updatedAt": "string"
  }
]

Example:

# Get all failed emails in January
curl -X GET "https://api.notifyhub.com/message-logs?channel=email&status=failed&dateFrom=2026-01-01&dateTo=2026-01-31" \
  -H "Authorization: Bearer TOKEN"

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "statusCode": 400,
  "message": "Descriptive error message",
  "error": "Bad Request"
}

Common causes:

  • Missing required fields
  • Invalid data format
  • Validation errors

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token|Token expired",
  "error": "Unauthorized"
}

Common causes:

  • Missing Authorization header
  • Invalid token
  • Expired token

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions",
  "error": "Forbidden"
}

Common causes:

  • Trying to access admin-only endpoint with user role
  • Accessing another organization's resources

404 Not Found

{
  "statusCode": 404,
  "message": "Resource not found",
  "error": "Not Found"
}

Common causes:

  • Invalid ID in path parameter
  • Resource deleted
  • Wrong endpoint URL

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Common causes:

  • Server issue
  • Database connectivity problem
  • External provider error

Action: Contact support if persistent

Rate Limits

Current Implementation:

  • No explicit platform rate limits
  • Provider-side limits apply (Lancola, Meta, SMTP)

Best Practices:

  • Batch requests (max 100 recipients per request recommended)
  • Implement exponential backoff for retries
  • Monitor delivery rates
  • Use campaigns for bulk sending

Future Rate Limits (planned):

  • 1000 requests/hour per organization
  • 10,000 messages/day per organization
  • Configurable based on plan

Webhooks (Future)

Coming soon: Real-time delivery notifications via webhooks.

Planned Events:

  • message.sent
  • message.delivered
  • message.failed
  • campaign.completed
  • campaign.failed

Changelog

v1.0.0 (January 2026)

  • Initial public API release
  • Authentication endpoints
  • User management
  • Contact and group management
  • Multi-channel messaging (SMS, Email, WhatsApp)
  • Campaign management
  • Message logs and analytics

Need help? Contact support@notifyhub.com