API Documentation

v1.0.0
← Back to Home

πŸ“– Introduction

Welcome to the SpryConnect API. Our RESTful API enables you to integrate SMS messaging, OTP verification, and Contact Management into your applications. Official SDKs are available for PHP, JavaScript/Node.js, Python, Java, C#, Ruby, and Go.

All requests and responses use JSON. Authentication is via API key headers.

Production Base URL: https://api.spryconnect.com/api/v1/external
  • SMS Messaging β€” Quick and bulk SMS with scheduling support
  • OTP Verification β€” Generate and verify one-time passwords
  • Contact Management β€” Organise contacts into groups
  • Account Management β€” Monitor usage statistics, delivery rates, and balance

πŸ” Authentication

All API requests require authentication using your API key and secret, passed as request headers.

Required Headers

x-api-key: YOUR_API_KEY
x-api-secret: YOUR_API_SECRET
Content-Type: application/json
Note: Never expose your credentials in client-side code or public repositories. To obtain credentials, log in to the SpryConnect dashboard β†’ Settings β†’ API Keys.

πŸš€ Getting Started

Here is a minimal cURL example to send your first SMS:

curl -X POST https://api.spryconnect.com/api/v1/external/sms/quick \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "233XXXXXXXXX",
    "from": "SenderID",
    "message": "Hello from SpryConnect!"
  }'

Standard Success Response (200/201)

{ "success": true, "message": "Operation completed successfully", "data": { ... } }

Standard Error Response (4xx/5xx)

{ "success": false, "message": "Error description", "error_code": "ERROR_CODE" }

⚠️ Error Codes

HTTP Status Error Code Description Common Cause
200 OK β€” Request successful Normal operation
201 Created β€” Resource created Contact/group created
400 Bad Request VALIDATION_ERROR Invalid request format Missing required fields
401 Unauthorized UNAUTHORIZED Authentication failed Invalid API key/secret
404 Not Found RESOURCE_NOT_FOUND Resource not found Invalid batch ID or contact
422 Unprocessable VALIDATION_ERROR Validation failed Invalid phone, empty message
429 Too Many Requests RATE_LIMIT_EXCEEDED Rate limit exceeded Too many requests in short period
500 Server Error SERVER_ERROR Server error Contact support

πŸ“¦ SDK Installation

Official SDKs are available for 7 languages. Download your preferred SDK, extract it into your project directory, then follow the numbered steps. Need help? Email support@spryconnect.com.

PHP SDK

Requirements: PHP 8.0+, Composer

⬇ Download PHP SDK
  1. 1
    Extract the SDK into your project root:
    unzip spryconnect-php-sdk.zip
  2. 2
    Add to your composer.json (recommended):
    {
        "repositories": [{ "type": "path", "url": "./spryconnect-php-sdk" }],
        "require": { "spryconnect/php-sdk": "*" }
    }
  3. 3
    Install dependencies:
    composer install
  4. 4
    Quick Start:
    <?php
    require 'vendor/autoload.php';
    use SpryConnect\SDK\SpryConnectClient;
    
    $client = new SpryConnectClient(
        apiKey: 'YOUR_API_KEY',
        apiSecret: 'YOUR_API_SECRET'
    );
    
    // Send SMS
    $response = $client->sms->sendQuick([
        'to'      => '233XXXXXXXXX',
        'from'    => 'YourBrand',
        'message' => 'Hello from SpryConnect!'
    ]);
    
    echo "Batch ID: " . $response['data']['batch_id'];
    
    // Check balance
    $balance = $client->account->getBalance();
    echo "Credits: " . $balance['data']['sms_credits'];
    
    // Generate OTP
    $otp = $client->otp->generate(['phone' => '233XXXXXXXXX', 'from' => 'YourBrand']);
To update: replace the spryconnect-php-sdk/ folder with the new version, then run composer update.

JavaScript / Node.js SDK

Requirements: Node.js 14+, npm

⬇ Download JS SDK
  1. 1
    Extract the SDK into your project directory:
    unzip spryconnect-js-sdk.zip
  2. 2
    Install from local path:
    npm install ./spryconnect-js-sdk
  3. 3
    Quick Start (CommonJS / Node.js):
    const { SpryConnectClient } = require('spryconnect-sdk');
    
    const client = new SpryConnectClient({
        apiKey: 'YOUR_API_KEY',
        apiSecret: 'YOUR_API_SECRET'
    });
    
    async function run() {
        // Send SMS
        const sms = await client.sms.sendQuick({
            to: '233XXXXXXXXX', from: 'YourBrand', message: 'Hello from SpryConnect!'
        });
        console.log('Batch ID:', sms.data.batch_id);
    
        // Check balance
        const bal = await client.account.getBalance();
        console.log('Credits:', bal.data.sms_credits);
    }
    
    run();
  4. 4
    TypeScript / ES Modules:
    import { SpryConnectClient } from 'spryconnect-sdk';
    
    const client = new SpryConnectClient({ apiKey: 'YOUR_KEY', apiSecret: 'YOUR_SECRET' });
    const response = await client.sms.sendQuick({
        to: '233XXXXXXXXX', from: 'YourBrand', message: 'Hello!'
    });
To update: run npm install ./spryconnect-js-sdk with the new extracted version.

Python SDK

Requirements: Python 3.8+, pip

⬇ Download Python SDK
  1. 1
    Extract the SDK:
    unzip spryconnect-python-sdk.zip
  2. 2
    Install from local directory:
    pip install ./spryconnect-python-sdk
  3. 3
    Quick Start:
    from spryconnect import SpryConnectClient
    
    client = SpryConnectClient(
        api_key='YOUR_API_KEY',
        api_secret='YOUR_API_SECRET'
    )
    
    # Send SMS
    response = client.sms.send_quick({
        'to': '233XXXXXXXXX',
        'from': 'YourBrand',
        'message': 'Hello from SpryConnect!'
    })
    print("Batch ID:", response['data']['batch_id'])
    
    # Check balance
    balance = client.account.get_balance()
    print("Credits:", balance['data']['sms_credits'])
    
    # Generate OTP
    otp = client.otp.generate({'phone': '233XXXXXXXXX', 'from': 'YourBrand'})
    print("OTP Reference:", otp['data']['reference'])
To update: pip uninstall spryconnect-sdk then pip install ./spryconnect-python-sdk (new version).

Java SDK

Requirements: Java 11+, Maven or Gradle

⬇ Download Java SDK
  1. 1
    Extract the SDK into your project directory:
    unzip spryconnect-java-sdk.zip
  2. 2
    Build the SDK:
    cd spryconnect-java-sdk
    mvn clean install
    cd ..
  3. 3
    Add to your pom.xml:
    <dependency>
        <groupId>com.spryconnect</groupId>
        <artifactId>spryconnect-sdk</artifactId>
        <version>1.0.0</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/spryconnect-java-sdk/target/spryconnect-sdk-1.0.0.jar</systemPath>
    </dependency>
  4. 4
    Quick Start:
    import com.spryconnect.sdk.SpryConnectClient;
    import java.util.Map;
    
    public class Example {
        public static void main(String[] args) {
            SpryConnectClient client = new SpryConnectClient.Builder()
                .apiKey("YOUR_API_KEY")
                .apiSecret("YOUR_API_SECRET")
                .build();
    
            try {
                // Send SMS
                Map<String, Object> response = client.sms.sendQuick(Map.of(
                    "to",      "233XXXXXXXXX",
                    "from",    "YourBrand",
                    "message", "Hello from SpryConnect!"
                ));
                System.out.println("Batch ID: " + response.get("batch_id"));
            } catch (Exception e) {
                System.err.println("Error: " + e.getMessage());
            }
        }
    }

C# / .NET SDK

Requirements: .NET Standard 2.0+ (.NET Core 2.0+, .NET 5+, .NET Framework 4.6.1+)

⬇ Download C# SDK
  1. 1
    Extract the SDK into your project directory:
    unzip spryconnect-csharp-sdk.zip
  2. 2
    Add a project reference (via CLI or .csproj):
    # Via CLI:
    dotnet add reference spryconnect-csharp-sdk/SpryConnect.SDK/SpryConnect.SDK.csproj
    
    # Or add to your .csproj file:
    <ItemGroup>
        <ProjectReference Include="spryconnect-csharp-sdk/SpryConnect.SDK/SpryConnect.SDK.csproj" />
    </ItemGroup>
  3. 3
    Quick Start:
    using SpryConnect.SDK;
    using System.Collections.Generic;
    using System.Threading.Tasks;
    
    class Program {
        static async Task Main(string[] args) {
            var client = new SpryConnectClient(
                apiKey: "YOUR_API_KEY",
                apiSecret: "YOUR_API_SECRET"
            );
    
            try {
                // Send SMS
                var response = await client.Sms.SendQuickAsync(new Dictionary<string, object> {
                    { "to",      "233XXXXXXXXX" },
                    { "from",    "YourBrand"    },
                    { "message", "Hello from SpryConnect!" }
                });
                Console.WriteLine("βœ… Message sent!");
    
                // Check balance
                var balance = await client.Account.GetBalanceAsync();
                Console.WriteLine($"SMS Credits: {balance["sms_credits"]}");
            } catch (Exception ex) {
                Console.WriteLine($"❌ Error: {ex.Message}");
            }
        }
    }

Ruby SDK

Requirements: Ruby 2.6+, Bundler

⬇ Download Ruby SDK
  1. 1
    Extract the SDK:
    unzip spryconnect-ruby-sdk.zip
  2. 2
    Add to your Gemfile:
    gem 'spryconnect', path: './spryconnect-ruby-sdk'
  3. 3
    Install:
    bundle install
  4. 4
    Quick Start:
    require 'spryconnect'
    
    client = SpryConnect::Client.new(
      api_key: 'YOUR_API_KEY',
      api_secret: 'YOUR_API_SECRET'
    )
    
    begin
      # Send SMS
      response = client.sms.send_quick(
        to: '233XXXXXXXXX',
        from: 'YourBrand',
        message: 'Hello from SpryConnect!'
      )
      puts "βœ… Batch ID: #{response['data']['batch_id']}"
    
      # Check balance
      balance = client.account.get_balance
      puts "Credits: #{balance['data']['sms_credits']}"
    rescue SpryConnect::Exceptions::ApiException => e
      puts "❌ Error: #{e.message}"
    end

Go SDK

Requirements: Go 1.19+

⬇ Download Go SDK
  1. 1
    Extract the SDK:
    unzip spryconnect-go-sdk.zip
  2. 2
    Add to your go.mod:
    require github.com/spryconnect/spryconnect-go v1.0.0
    
    replace github.com/spryconnect/spryconnect-go => ./spryconnect-go-sdk
  3. 3
    Download dependencies:
    go mod tidy
  4. 4
    Quick Start:
    package main
    
    import (
        "fmt"
        "log"
        "github.com/spryconnect/spryconnect-go/spryconnect"
    )
    
    func main() {
        client := spryconnect.NewClient("YOUR_API_KEY", "YOUR_API_SECRET")
    
        // Send SMS
        response, err := client.SMS.SendQuick(map[string]interface{}{
            "to":      "233XXXXXXXXX",
            "from":    "YourBrand",
            "message": "Hello from SpryConnect!",
        })
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println("βœ… Batch ID:", response["batch_id"])
    
        // Check balance
        balance, _ := client.Account.GetBalance()
        fmt.Println("SMS Credits:", balance["sms_credits"])
    }

SMS

POST

Send Quick SMS

/external/sms/quick

Headers

x-api-key: YOUR_API_KEY
x-api-secret: YOUR_API_SECRET
Content-Type: application/json

Request Body

{ "to": "233XXXXXXXXX", "from": "SenderID", "message": "Simple Test" }

Response 200 OK

{
  "success": true,
  "message": "Your messages are being processed and will be delivered shortly.",
  "data": { "batch_id": "QM-970184-1744958266", "total_recipients": 1, "credit_cost": 1, "scheduled": false }
}
POST

Send Quick SMS Scheduled

/external/sms/quick

Request Body

{ "to": "233XXXXXXXXX", "from": "SenderID", "message": "Scheduled test message", "schedule_date": "2025-11-14 11:15" }

Response 200 OK

{ "success": true, "message": "Your messages are being processed.", "data": { "batch_id": "QM-970184-1744958266", "scheduled": true } }
POST

Send Bulk SMS

/external/sms/bulk

Request Body

{
  "messages": [
    { "to": "233XXXXXXXXX", "from": "SenderID", "message": "Hello from SpryConnect!" },
    { "to": "233XXXXXXXXY", "from": "SenderID", "message": "Hello from SpryConnect!" }
  ]
}

Response 200 OK

{ "success": true, "message": "Bulk messages processed", "data": { "total_messages": 2, "successful": 2, "failed": 0, "batch_ids": ["BM-965130-1744959381"], "scheduled": false } }
POST

Send Bulk SMS Scheduled

/external/sms/bulk

Request Body

{ "messages": [ { "to": "233XXXXXXXXX", "from": "SenderID", "message": "Scheduled bulk message" } ], "schedule_date": "2025-10-07 03:30" }
GET

SMS Batch Status

/external/sms/batch/{batch_id}/status

Response 200 OK

{
  "success": true,
  "data": {
    "batch_id": "BM-518430-1742466970",
    "status": "COMPLETED",
    "progress": 100,
    "total": 4, "processed": 4, "succeeded": 4, "failed": 0,
    "started_at": "2025-03-20T10:36:10Z",
    "completed_at": "2025-03-20T10:40:01Z",
    "is_completed": true, "error": null
  }
}
POST

Resend Failed SMS

/external/sms/quick/{batch_id}/resend

Response β€” No failed messages

{ "success": false, "message": "No failed messages found for this batch ID or batch does not belong to you", "error_code": "RESOURCE_NOT_FOUND" }
GET

Get Message Logs

/external/sms/logs?isPaginated=true&page=1&limit=30

Response 200 OK

{
  "success": true,
  "data": {
    "total": 295, "per_page": 30, "current_page": 1, "last_page": 10,
    "data": [
      { "id": 265, "batch_id": "QM-219917-1744533404", "sender_id": "SenderID",
        "message": "...", "total_recipients": 2, "credit_cost": 4, "status": "COMPLETED",
        "created_at": "2025-04-13T08:36:44Z" }
    ]
  }
}
GET

Check Message Batch Details

/external/sms/logs/{batch_id}
GET

Check Message Batch Status

/external/sms/logs/{batch_id}/status

Response 200 OK

{ "success": true, "data": { "message_id": "9573220250310113954", "status": "DELIVRD", "recipient": "233XXXXXXXXX", "sender": "SenderID", "sent_at": "2025-03-10T11:39:54Z", "delivered_at": null, "batch_id": "QM-733872-1741606794" } }
GET

Check Message Details

/external/sms/logs/{batch_id}/messages
GET

Check Message Status

/external/sms/logs/{batch_id}/messages/status

Accounts

GET

Get Delivery Rates

/external/account/delivery-rates?startDate=2025-03-01&endDate=2025-03-31

Response 200 OK

{
  "success": true,
  "data": {
    "delivery_rates": [
      { "gateway": "All Messages", "total": 141, "delivered": 139, "ack": 0, "expired": 0, "failed": 0, "pending": 2, "delivery_rate": 98.58, "avg_delivery_time": "N/A" }
    ]
  }
}
GET

Get Usage Statistics

/external/account/stats

Response 200 OK

{
  "success": true,
  "data": {
    "today":  { "total": 14, "delivered": 14, "expired": 0, "failed": 0, "pending": 0, "creditUsed": 14 },
    "week":   { "total": 55, "delivered": 39, "expired": 0, "failed": 4,  "pending": 12, "creditUsed": 86 },
    "month":  { "total": 234, "delivered": 188, "expired": 0, "failed": 10, "pending": 36, "creditUsed": 330 }
  }
}
GET

Check Balance

/external/account/balance

Response 200 OK

{ "success": true, "data": { "sms_credits": 141, "whatsapp_credits": 0, "voice_credits": 49937, "last_updated": "2025-04-18T06:56:21Z" } }

OTP

POST

Generate OTP

/external/generate/otp

Request Body

{ "phone": "233XXXXXXXXX", "from": "SenderID", "expiry": 5 }

Response 200 OK

{ "success": true, "message": "OTP sent successfully", "data": { "reference": "OTP-XXXXXXXXXX", "expires_in": 300 } }
POST

Verify OTP

/external/verify/otp

Request Body

{ "reference": "OTP-XXXXXXXXXX", "otp": "123456" }

Response 200 OK

{ "success": true, "message": "OTP verified successfully", "data": { "verified": true } }

Contacts

GET

List All Contact Groups

/external/contacts/groups
{ "success": true, "data": [ { "id": 1, "name": "Customers", "count": 120 } ] }
GET

Get Single Contact Group

/external/contacts/groups/{id}
POST

Create Contact Group

/external/contacts/groups
{ "name": "VIP Customers", "description": "Top-tier clients" }
PUT

Update Contact Group

/external/contacts/groups/{id}
{ "name": "Updated Group Name" }
DELETE

Delete Contact Group

/external/contacts/groups/{id}
GET

List All Contacts

/external/contacts?group_id=1&page=1&limit=50
GET

Get Single Contact

/external/contacts/{id}
POST

Create Contact

/external/contacts
{ "first_name": "John", "last_name": "Doe", "phone": "233XXXXXXXXX", "email": "john@example.com", "group_id": 1 }
POST

Batch Create Contacts

/external/contacts/batch
{ "group_id": 1, "contacts": [ { "first_name": "Jane", "last_name": "Doe", "phone": "233XXXXXXXXX" } ] }
PUT

Update Contact

/external/contacts/{id}
{ "first_name": "Updated Name", "phone": "233XXXXXXXXX" }
DELETE

Delete Contact

/external/contacts/{id}
POST

Import Contacts from File

/external/contacts/import
Upload a .xlsx file using multipart/form-data. Include group_id as a form field. Download Template β†’

Integrations

πŸ›’

SpryConnect for WooCommerce

v1.3.0 Production Ready βœ…

Send automated SMS notifications to WooCommerce customers on every order status change. Powered by the SpryConnect API.

⬇ Download Plugin
Requirements: WordPress 5.8+, WooCommerce 6.0+, PHP 7.4+, Active SpryConnect account

✨ Key Features

βœ“ Automated SMS on all 7 order statuses
βœ“ Customizable message templates
βœ“ 12 dynamic template variables
βœ“ SMS logs with filtering & pagination
βœ“ API connection testing built-in
βœ“ Real-time SMS character counter
βœ“ Asynchronous sending (no checkout impact)
βœ“ Lightweight β€” no bloat

πŸš€ Installation

  1. 1
    Download the plugin ZIP using the button above.
  2. 2
    Install on WordPress:
    WordPress Admin β†’ Plugins β†’ Add New β†’ Upload Plugin
    β†’ Choose ZIP file β†’ Install Now β†’ Activate
  3. 3
    Configure API credentials:
    WordPress Admin β†’ SpryConnect β†’ Settings
    β†’ Enter API Key, API Secret, Sender ID
    β†’ Click "Test Connection" β€” verify βœ… success
    β†’ Enable desired order status notifications
    β†’ Click "Save Changes"
  4. 4
    Test it works: Place a test order, change its status to Processing, and confirm an SMS is received. Then check SpryConnect β†’ SMS Logs for the log entry.

πŸ“‹ Supported Order Statuses

Status Trigger Default SMS Sent
Pending Payment Order placed, awaiting payment Optional
Processing Payment received, order being prepared βœ“ Enabled
On Hold Awaiting payment confirmation Optional
Completed Order fulfilled & delivered βœ“ Enabled
Cancelled Order cancelled by customer or admin Optional
Refunded Order refunded Optional
Failed Payment failed Optional

πŸ”€ Template Variables

Use these in your SMS templates to personalise messages automatically:

{customer_name}    β†’ Customer's full name
{customer_first}   β†’ Customer's first name
{order_number}     β†’ WooCommerce order number
{order_id}         β†’ Order ID
{order_total}      β†’ Total with currency symbol
{order_status}     β†’ Current order status label
{order_date}       β†’ Order placement date
{payment_method}   β†’ Payment method used
{shipping_method}  β†’ Shipping method
{shop_name}        β†’ Your store name
{shop_url}         β†’ Your store URL
{shop_email}       β†’ Your store email

πŸ’¬ Example SMS Template

Hi {customer_first}! Your {shop_name} order #{order_number} is now {order_status}. Total: {order_total}. Questions? Email {shop_email}

πŸ”§ Troubleshooting

SMS not sending? β€” Verify your API credentials via Test Connection. Ensure the customer phone number includes country code (e.g. 233XXXXXXXXX).
Plugin not activating? β€” Confirm WooCommerce is installed and active first. Check PHP version is 7.4+.
Logs empty? β€” Check that at least one notification status is enabled in Settings and that orders exist with phone numbers attached.