API Documentation
v1.0.0π 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.
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
π 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
-
1
Extract the SDK into your project root:
unzip spryconnect-php-sdk.zip
-
2
Add to your
composer.json(recommended):{ "repositories": [{ "type": "path", "url": "./spryconnect-php-sdk" }], "require": { "spryconnect/php-sdk": "*" } } -
3
Install dependencies:
composer install
-
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']);
spryconnect-php-sdk/ folder with
the new version, then run composer update.JavaScript / Node.js SDK
Requirements: Node.js 14+, npm
-
1
Extract the SDK into your project directory:
unzip spryconnect-js-sdk.zip
-
2
Install from local path:
npm install ./spryconnect-js-sdk
-
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
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!' });
npm install ./spryconnect-js-sdk with the
new extracted version.Python SDK
Requirements: Python 3.8+, pip
-
1
Extract the SDK:
unzip spryconnect-python-sdk.zip
-
2
Install from local directory:
pip install ./spryconnect-python-sdk
-
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'])
pip uninstall spryconnect-sdk then
pip install ./spryconnect-python-sdk (new version).
Java SDK
Requirements: Java 11+, Maven or Gradle
-
1
Extract the SDK into your project directory:
unzip spryconnect-java-sdk.zip
-
2
Build the SDK:
cd spryconnect-java-sdk mvn clean install cd ..
-
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
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+)
-
1
Extract the SDK into your project directory:
unzip spryconnect-csharp-sdk.zip
-
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
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
-
1
Extract the SDK:
unzip spryconnect-ruby-sdk.zip
-
2
Add to your
Gemfile:gem 'spryconnect', path: './spryconnect-ruby-sdk'
-
3
Install:
bundle install
-
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+
-
1
Extract the SDK:
unzip spryconnect-go-sdk.zip
-
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
Download dependencies:
go mod tidy
-
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
Send Quick SMS
Headers
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 }
}
Send Quick SMS Scheduled
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 } }
Send Bulk SMS
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 } }
Send Bulk SMS Scheduled
Request Body
{ "messages": [ { "to": "233XXXXXXXXX", "from": "SenderID", "message": "Scheduled bulk message" } ], "schedule_date": "2025-10-07 03:30" }
SMS Batch 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
}
}
Resend Failed SMS
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 Message Logs
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" }
]
}
}
Check Message Batch Details
Check Message Batch 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" } }
Check Message Details
Check Message Status
Accounts
Get Delivery Rates
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 Usage Statistics
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 }
}
}
Check Balance
Response 200 OK
{ "success": true, "data": { "sms_credits": 141, "whatsapp_credits": 0, "voice_credits": 49937, "last_updated": "2025-04-18T06:56:21Z" } }
OTP
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 } }
Verify OTP
Request Body
{ "reference": "OTP-XXXXXXXXXX", "otp": "123456" }
Response 200 OK
{ "success": true, "message": "OTP verified successfully", "data": { "verified": true } }
Contacts
List All Contact Groups
{ "success": true, "data": [ { "id": 1, "name": "Customers", "count": 120 } ] }
Get Single Contact Group
Create Contact Group
{ "name": "VIP Customers", "description": "Top-tier clients" }
Update Contact Group
{ "name": "Updated Group Name" }
Delete Contact Group
List All Contacts
Get Single Contact
Create Contact
{ "first_name": "John", "last_name": "Doe", "phone": "233XXXXXXXXX", "email": "john@example.com", "group_id": 1 }
Batch Create Contacts
{ "group_id": 1, "contacts": [ { "first_name": "Jane", "last_name": "Doe", "phone": "233XXXXXXXXX" } ] }
Update Contact
{ "first_name": "Updated Name", "phone": "233XXXXXXXXX" }
Delete Contact
Import Contacts from File
.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.
β¨ Key Features
π Installation
-
1
Download the plugin ZIP using the button above.
-
2
Install on WordPress:
WordPress Admin β Plugins β Add New β Upload Plugin β Choose ZIP file β Install Now β Activate
-
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
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
233XXXXXXXXX).