API Documentation

Auth Endpoints

curl -X POST https://api.cpl.com.ng/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'

{
  "success": true,
  "data": {
    "user": { "id": 1, "name": "John Doe", "role": "client" },
    "token": "1|abc123xyz..."
  }
}

Get delivery status of a specific message.

curl https://api.cpl.com.ng/api/client/sms/status/12345 \
  -H "Authorization: Bearer cpl_YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "data": {
    "id": 12345,
    "user_id": 1,
    "recipient_phone": "+2348012345678",
    "sender_id_value": "MyBrand",
    "message_text": "Your OTP is 123456.",
    "segments_count": 1,
    "cost": "2.50",
    "status": "delivered",
    "created_at": "2025-04-20T10:30:00.000000Z",
    "updated_at": "2025-04-20T10:30:08.000000Z"
  }
}

Status Values

List all messages sent from your account with pagination and filters.

Get the status and progress of a bulk SMS campaign.

{
  "success": true,
  "data": {
    "id": 42,
    "name": "April Promo",
    "status": "processing",
    "total_recipients": 1500,
    "sent": 900,
    "delivered": 850,
    "failed": 12,
    "total_cost": 3750.00,
    "scheduled_at": null,
    "created_at": "2025-04-20T08:00:00Z"
  }
}

Detailed wallet info including balance and currency.

Paginated list of all credits, debits, and SMS charges.

Create a Paystack payment link to fund your wallet.

curl -X POST https://api.cpl.com.ng/api/client/wallet/fund/initialize \
  -H "Authorization: Bearer cpl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"amount": 5000}'

{
  "data": {
    "reference": "CPL-20250420-XYZ",
    "authorization_url": "https://checkout.paystack.com/abc123",
    "amount": 5000,
    "currency": "NGN"
  }
}

Verify a Paystack payment and credit the wallet if successful. Call this after the user returns from Paystack checkout.

curl https://api.cpl.com.ng/api/client/wallet/fund/verify/CPL-20250420-XYZ \
  -H "Authorization: Bearer cpl_YOUR_API_KEY" \
  -H "Accept: application/json"

List all your sender IDs and their approval status.

List only approved sender IDs available for sending.

Generate a new HTTP API key. The full key is only shown once — store it securely.

curl -X POST https://api.cpl.com.ng/api/client/credentials/http/create \
  -H "Authorization: Bearer cpl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name": "My Server Key"}'

// 201 Created
{
  "success": true,
  "message": "API key created successfully. Please copy it now as it will not be shown again.",
  "data": {
    "id": 4,
    "name": "My Server Key",
    "api_key": "cpl_AbCdEfGhIjKlMnOpQrStUvWxYz...",
    "created_at": "2025-04-20T10:30:00.000000Z"
  }
}

Permanently revoke an API key by its ID. This action cannot be undone.

View your SMPP credentials and connection status.

Generate SMPP credentials. Username is auto-assigned. Password shown once.

// 201 Created
{
  "success": true,
  "message": "SMPP credentials generated successfully. Please copy them now as the password will not be shown again.",
  "data": {
    "id": 1,
    "smpp_username": "smpp_AbCdEfGhIj",
    "smpp_password": "xK9mP2qR",
    "status": "active",
    "connection_info": {
      "host": "smpp.cpl.com.ng",
      "port": 2775,
      "bind_type": "transceiver"
    },
    "created_at": "2025-04-20T10:30:00.000000Z"
  }
}

Reset your SMPP password. New password shown once; all active sessions are terminated.

Paystack payment webhook. Verifies the HMAC-SHA512 x-paystack-signature header and credits the user's wallet on successful charge.success events. Configure this URL in your Paystack dashboard settings.