API Documentation — PeakCampaign

Authentication

All API requests require a valid Bearer token in the Authorization header. You can generate API tokens from your Developer Tools dashboard after signing in.

Every request must include these headers:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json

Don't have an API key? Create a free account and generate one from the Developer Tools section.

Base URL

All API endpoints are relative to the following base URL:

https://paynex.org/api

Rate Limiting

API requests are rate-limited to ensure fair usage and platform stability.

Scope	Limit	Window
General API	60 requests	Per minute
SMS Sending	Tier-based	Per account plan

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Limit) are included in every response.

Response Format

All responses follow a consistent JSON structure:

{
  "status": true,
  "message": "Descriptive success message",
  "data": { }
}

Standard HTTP status codes are used:

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request
`401`	Unauthorized
`404`	Not Found
`422`	Validation Error
`429`	Too Many Requests
`500`	Server Error

Endpoint Reference

GET /balance Get Wallet Balance

Retrieve your current wallet balance across all channels.

Parameters

No parameters required.

Code Examples

curl -X GET "https://paynex.org/api/balance" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get('https://paynex.org/api/balance');

$data = $response->json();

const response = await fetch('https://paynex.org/api/balance', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();

import requests

response = requests.get(
    'https://paynex.org/api/balance',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
    }
)

data = response.json()

Example Response 200

{
  "status": true,
  "message": "Wallet balance retrieved successfully",
  "data": {
    "main_balance": "11,711.00",
    "sms_balance": "0.00",
    "email_balance": "0.00",
    "whatsapp_balance": "0.00",
    "total_balance": "11,711.00",
    "currency": "NGN"
  }
}

POST /sender-id Create Sender ID

Create a new Sender ID for SMS messages. Sender IDs are pending admin approval after creation.

Parameters

Name	Type	Required	Description
`sender_id`	string	Yes	Alphanumeric only, max 11 characters

Code Examples

curl -X POST "https://paynex.org/api/sender-id" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "YourBrand"}'

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->post('https://paynex.org/api/sender-id', [
        'sender_id' => 'YourBrand',
    ]);

$data = $response->json();

const response = await fetch('https://paynex.org/api/sender-id', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ sender_id: 'YourBrand' })
});

const data = await response.json();

import requests

response = requests.post(
    'https://paynex.org/api/sender-id',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
    },
    json={'sender_id': 'YourBrand'}
)

data = response.json()

Example Response 201

{
  "status": true,
  "message": "Sender ID created successfully and pending approval",
  "data": {
    "id": 1,
    "sender_id": "YOURBRAND",
    "status": "pending",
    "created_at": "2024-01-15 10:30:00"
  }
}

GET /sender-id List Sender IDs

Retrieve all sender IDs for the authenticated user.

Parameters

No parameters required.

Code Examples

curl -X GET "https://paynex.org/api/sender-id" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get('https://paynex.org/api/sender-id');

$data = $response->json();

const response = await fetch('https://paynex.org/api/sender-id', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();

import requests

response = requests.get(
    'https://paynex.org/api/sender-id',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
    }
)

data = response.json()

Example Response 200

{
  "status": true,
  "message": "Sender IDs retrieved successfully",
  "data": [
    {
      "id": 1,
      "sender_id": "YOURBRAND",
      "status": "approved",
      "declined_reason": null,
      "approved_at": "2024-01-15 12:00:00",
      "declined_at": null,
      "created_at": "2024-01-15 10:30:00"
    },
    {
      "id": 2,
      "sender_id": "MYCOMPANY",
      "status": "pending",
      "declined_reason": null,
      "approved_at": null,
      "declined_at": null,
      "created_at": "2024-01-16 09:15:00"
    }
  ]
}

GET /sender-id/{senderId}/status Sender ID Status

Check the approval status of a specific sender ID.

Path Parameters

Name	Type	Required	Description
`senderId`	string	Yes	The sender ID name (e.g., YOURBRAND)

Code Examples

curl -X GET "https://paynex.org/api/sender-id/YOURBRAND/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$senderId = 'YOURBRAND';

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get("https://paynex.org/api/sender-id/{$senderId}/status");

$data = $response->json();

const senderId = 'YOURBRAND';

const response = await fetch(`https://paynex.org/api/sender-id/${senderId}/status`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();

import requests

sender_id = 'YOURBRAND'

response = requests.get(
    f'https://paynex.org/api/sender-id/{sender_id}/status',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
    }
)

data = response.json()

Example Response 200

{
  "status": true,
  "message": "Sender ID status retrieved successfully",
  "data": {
    "id": 1,
    "sender_id": "YOURBRAND",
    "status": "approved",
    "declined_reason": null,
    "approved_at": "2024-01-15 12:00:00",
    "declined_at": null,
    "created_at": "2024-01-15 10:30:00"
  }
}

Ready to Send Your First SMS?

Create a free account, get your API key, and start integrating in minutes.

Get Started Free Sign In

POST /sms/send Send SMS

Send SMS messages to one or multiple recipients.

Parameters

Name	Type	Required	Description
`sender_id`	string	Yes	Your approved sender ID
`recipients`	string	Yes	Comma-separated phone numbers (e.g., "08012345678,08087654321")
`message`	string	Yes	Message content (max: 1000 characters)
`route_id`	integer	No	SMS route ID (uses default route if not provided)

Code Examples

curl -X POST "https://paynex.org/api/sms/send" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "YourBrand",
    "recipients": "08012345678,08087654321",
    "message": "Hello from PeakCampaign API!"
  }'

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->post('https://paynex.org/api/sms/send', [
        'sender_id'  => 'YourBrand',
        'recipients' => '08012345678,08087654321',
        'message'    => 'Hello from PeakCampaign API!',
    ]);

$data = $response->json();

const response = await fetch('https://paynex.org/api/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sender_id: 'YourBrand',
    recipients: '08012345678,08087654321',
    message: 'Hello from PeakCampaign API!'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://paynex.org/api/sms/send',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
    },
    json={
        'sender_id': 'YourBrand',
        'recipients': '08012345678,08087654321',
        'message': 'Hello from PeakCampaign API!'
    }
)

data = response.json()

Example Response 201

{
  "status": true,
  "message": "SMS request submitted successfully",
  "data": {
    "request_id": 123,
    "reference": "SMS-123",
    "recipients_count": 2,
    "cost": "10.00",
    "status": "pending"
  }
}

GET /sms/history Message History

Retrieve paginated SMS message history with optional filtering.

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 20, max: 100)
`status`	string	No	Filter by: pending, processing, completed, partially_completed, failed
`from_date`	date	No	Start date filter (YYYY-MM-DD)
`to_date`	date	No	End date filter (YYYY-MM-DD)

Code Examples

curl -X GET "https://paynex.org/api/sms/history?page=1&per_page=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get('https://paynex.org/api/sms/history', [
        'page'     => 1,
        'per_page' => 20,
        'status'   => 'completed',
    ]);

$data = $response->json();

const params = new URLSearchParams({
  page: 1,
  per_page: 20,
  status: 'completed'
});

const response = await fetch(`https://paynex.org/api/sms/history?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();

import requests

response = requests.get(
    'https://paynex.org/api/sms/history',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
    },
    params={
        'page': 1,
        'per_page': 20,
        'status': 'completed'
    }
)

data = response.json()

Example Response 200

{
  "status": true,
  "message": "Message history retrieved successfully",
  "data": [
    {
      "id": 123,
      "reference": "SMS-123",
      "message": "Your message content",
      "recipients_count": 2,
      "status": "completed",
      "cost": "10.00",
      "created_at": "2024-01-15 10:30:00"
    }
  ],
  "pagination": {
    "total": 50,
    "per_page": 20,
    "current_page": 1,
    "last_page": 3,
    "from": 1,
    "to": 20
  }
}

GET /sms/status/{reference} Message Status

Get detailed delivery status for a specific message by its reference.

Path Parameters

Name	Type	Required	Description
`reference`	string	Yes	Message reference (format: SMS-{id})

Code Examples

curl -X GET "https://paynex.org/api/sms/status/SMS-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$reference = 'SMS-123';

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get("https://paynex.org/api/sms/status/{$reference}");

$data = $response->json();

const reference = 'SMS-123';

const response = await fetch(`https://paynex.org/api/sms/status/${reference}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();

import requests

reference = 'SMS-123'

response = requests.get(
    f'https://paynex.org/api/sms/status/{reference}',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
    }
)

data = response.json()

Example Response 200

{
  "status": true,
  "message": "Message status retrieved successfully",
  "data": {
    "id": 123,
    "reference": "SMS-123",
    "message": "Your message content",
    "status": "completed",
    "total_recipients": 2,
    "delivery_stats": {
      "delivered": 2,
      "failed": 0,
      "pending": 0
    },
    "created_at": "2024-01-15 10:30:00"
  }
}

Error Codes

When an error occurs, the API returns a JSON response with status: false and a descriptive error message.

Status Code	Type	Description
`400`	Bad Request	The request was malformed or missing required fields
`401`	Unauthorized	Invalid or missing API token
`404`	Not Found	The requested resource does not exist
`422`	Validation Error	Request body failed validation rules
`429`	Too Many Requests	Rate limit exceeded — slow down and retry
`500`	Server Error	An unexpected error occurred on our end

Example Error Responses

401 Unauthorized

{
  "message": "Unauthenticated."
}

422 Validation Error

{
  "status": false,
  "message": "Sender ID is required",
  "errors": {
    "sender_id": [
      "Sender ID is required"
    ]
  }
}

404 Not Found

{
  "status": false,
  "message": "Resource not found"
}

500 Server Error

{
  "status": false,
  "message": "An error occurred. Please try again."
}

PeakCampaign
API Documentation

Authentication

Base URL

Rate Limiting

Response Format

Endpoint Reference

Parameters

Code Examples

Example Response 200

Parameters

Code Examples

Example Response 201

Parameters

Code Examples

Example Response 200

Path Parameters

Code Examples

Example Response 200

Ready to Send Your First SMS?

Parameters

Code Examples

Example Response 201

Query Parameters

Code Examples

Example Response 200

Path Parameters

Code Examples

Example Response 200

Error Codes

Example Error Responses

Ready to Start Building?

PeakCampaignAPI Documentation

Authentication

Base URL

Rate Limiting

Response Format

Endpoint Reference

Parameters

Code Examples

Example Response 200

Parameters

Code Examples

Example Response 201

Parameters

Code Examples

Example Response 200

Path Parameters

Code Examples

Example Response 200

Ready to Send Your First SMS?

Parameters

Code Examples

Example Response 201

Query Parameters

Code Examples

Example Response 200

Path Parameters

Code Examples

Example Response 200

Error Codes

Example Error Responses

Ready to Start Building?

PeakCampaign
API Documentation