ClickSend via SkillBoss API Hub#

Send SMS, MMS, and voice messages via SkillBoss API Hub. Manage contacts and lists, and track message delivery.

Quick Start#

python

import requests, os

SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"]

response = requests.post(
    "https://api.skillboss.com/v1/run",
    headers={
        "Authorization": f"Bearer {SKILLBOSS_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "prelude/notify-send",
        "inputs": {
            "template_id": "your_template_id",  # Configure in Prelude dashboard
            "to": "+15551234567",
            "variables": {"message": "Hello from SkillBoss!"}
        }
    }
)
result = response.json()
print(result)

Base URL#

text

https://api.skillboss.com/v1/run

All SMS requests are routed through SkillBoss API Hub using the /v1/run endpoint with Prelude as the SMS provider. Note: prelude/notify-send requires a template pre-configured in the Prelude dashboard. For OTP verification, use prelude/verify-send / prelude/verify-check.

Authentication#

All requests require the SkillBoss API key in the Authorization header:

text

Authorization: Bearer $SKILLBOSS_API_KEY

Environment Variable: Set your API key as SKILLBOSS_API_KEY:

bash

export SKILLBOSS_API_KEY="YOUR_API_KEY"

Getting Your API Key#

1. Sign in or create an account at heybossai.com
2. Go to your account settings
3. Copy your API key

API Reference#

Response Format#

All SkillBoss API Hub responses follow this structure:

json

{
  "status": "success",
  "result": { ... }
}

---

Account#

Get Account#

bash

GET /clicksend/v3/account

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here's your account",
  "data": {
    "user_id": 672721,
    "username": "user@example.com",
    "user_email": "user@example.com",
    "balance": "2.005718",
    "user_phone": "+18019234886",
    "user_first_name": "John",
    "user_last_name": "Doe",
    "country": "US",
    "default_country_sms": "US",
    "timezone": "America/Chicago",
    "_currency": {
      "currency_name_short": "USD",
      "currency_prefix_d": "$"
    }
  }
}

---

SMS#

Send SMS#

bash

POST /clicksend/v3/sms/send
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Hello from ClickSend!",
      "source": "api"
    }
  ]
}

Parameters:

FieldTypeDescriptiontostringRecipient phone number (E.164 format)bodystringSMS message contentsourcestringSource identifier (e.g., "api", "sdk")fromstringSender ID (optional)scheduleintUnix timestamp for scheduled send (optional)custom_stringstringCustom reference (optional)

Get SMS Price#

bash

POST /clicksend/v3/sms/price
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Test message",
      "source": "api"
    }
  ]
}

SMS History#

bash

GET /clicksend/v3/sms/history

Query Parameters:

ParameterDescriptiondate_fromUnix timestamp for start datedate_toUnix timestamp for end datepagePage number (default: 1)limitResults per page (default: 15)

Inbound SMS#

bash

GET /clicksend/v3/sms/inbound

SMS Receipts (Delivery Reports)#

bash

GET /clicksend/v3/sms/receipts

Cancel Scheduled SMS#

bash

PUT /clicksend/v3/sms/{message_id}/cancel

Cancel All Scheduled SMS#

bash

PUT /clicksend/v3/sms/cancel-all

---

SMS Templates#

List Templates#

bash

GET /clicksend/v3/sms/templates

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are your templates.",
  "data": {
    "total": 1,
    "per_page": 15,
    "current_page": 1,
    "data": [
      {
        "template_id": 632497,
        "body": "Hello {name}, this is a test message.",
        "template_name": "Test Template"
      }
    ]
  }
}

Create Template#

bash

POST /clicksend/v3/sms/templates
Content-Type: application/json

{
  "template_name": "Welcome Message",
  "body": "Hello {name}, welcome to our service!"
}

Update Template#

bash

PUT /clicksend/v3/sms/templates/{template_id}
Content-Type: application/json

{
  "template_name": "Updated Template",
  "body": "Updated message content"
}

Delete Template#

bash

DELETE /clicksend/v3/sms/templates/{template_id}

---

MMS#

Send MMS#

bash

POST /clicksend/v3/mms/send
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Check out this image!",
      "media_file": "https://example.com/image.jpg",
      "source": "api"
    }
  ]
}

MMS History#

bash

GET /clicksend/v3/mms/history

Get MMS Price#

bash

POST /clicksend/v3/mms/price
Content-Type: application/json

{
  "messages": [...]
}

MMS Receipts#

bash

GET /clicksend/v3/mms/receipts

---

Voice#

Send Voice Message#

bash

POST /clicksend/v3/voice/send
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Hello, this is a voice message.",
      "voice": "female",
      "lang": "en-us",
      "source": "api"
    }
  ]
}

Voice Parameters:

FieldDescriptiontoRecipient phone numberbodyText to be spokenvoiceVoice gender: male or female``langLanguage code (e.g., en-us, en-gb, de-de)scheduleUnix timestamp for scheduled callrequire_inputRequire keypad input (0-1)machine_detectionDetect answering machine (0-1)

Available Languages#

bash

GET /clicksend/v3/voice/lang

Returns list of supported languages with codes and available genders.

Voice History#

bash

GET /clicksend/v3/voice/history

Note: Requires voice access enabled on account.

Get Voice Price#

bash

POST /clicksend/v3/voice/price

Cancel Voice Message#

bash

PUT /clicksend/v3/voice/{message_id}/cancel

---

Contact Lists#

List All Lists#

bash

GET /clicksend/v3/lists

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are your contact lists.",
  "data": {
    "total": 2,
    "data": [
      {
        "list_id": 3555277,
        "list_name": "Opt-Out List",
        "_contacts_count": 0
      },
      {
        "list_id": 3555278,
        "list_name": "Example List",
        "_contacts_count": 10
      }
    ]
  }
}

Get List#

bash

GET /clicksend/v3/lists/{list_id}

Create List#

bash

POST /clicksend/v3/lists
Content-Type: application/json

{
  "list_name": "My New List"
}

Update List#

bash

PUT /clicksend/v3/lists/{list_id}
Content-Type: application/json

{
  "list_name": "Updated List Name"
}

Delete List#

bash

DELETE /clicksend/v3/lists/{list_id}

Remove Duplicates#

bash

PUT /clicksend/v3/lists/{list_id}/remove-duplicates

---

Contacts#

List Contacts in a List#

bash

GET /clicksend/v3/lists/{list_id}/contacts

Query Parameters:

ParameterDescriptionpagePage numberlimitResults per pageupdated_afterFilter contacts updated after timestamp

Get Contact#

bash

GET /clicksend/v3/lists/{list_id}/contacts/{contact_id}

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "data": {
    "contact_id": 1581565666,
    "list_id": 3555278,
    "phone_number": "+18019234886",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "custom_1": "",
    "custom_2": "",
    "custom_3": "",
    "custom_4": "",
    "organization_name": "",
    "address_city": "",
    "address_state": "",
    "address_country": "US"
  }
}

Create Contact#

bash

POST /clicksend/v3/lists/{list_id}/contacts
Content-Type: application/json

{
  "phone_number": "+15551234567",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com"
}

Contact Fields:

FieldDescriptionphone_numberPhone number (E.164 format)first_nameFirst namelast_nameLast nameemailEmail addressfax_numberFax numberorganization_nameCompany namecustom_1 - custom_4Custom fieldsaddress_line_1, address_line_2Addressaddress_city, address_state, address_postal_code, address_countryAddress components

Update Contact#

bash

PUT /clicksend/v3/lists/{list_id}/contacts/{contact_id}
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Smith"
}

Delete Contact#

bash

DELETE /clicksend/v3/lists/{list_id}/contacts/{contact_id}

Copy Contact to Another List#

bash

PUT /clicksend/v3/lists/{from_list_id}/contacts/{contact_id}/copy/{to_list_id}

Transfer Contact to Another List#

bash

PUT /clicksend/v3/lists/{from_list_id}/contacts/{contact_id}/transfer/{to_list_id}

---

Email Addresses#

List Verified Email Addresses#

bash

GET /clicksend/v3/email/addresses

Add Email Address#

bash

POST /clicksend/v3/email/addresses
Content-Type: application/json

{
  "email_address": "sender@example.com"
}

Delete Email Address#

bash

DELETE /clicksend/v3/email/addresses/{email_address_id}

---

Utility Endpoints#

List Countries#

bash

GET /clicksend/v3/countries

Returns list of all supported countries with codes.

---

Pagination#

ClickSend uses page-based pagination:

bash

GET /clicksend/v3/lists?page=2&limit=50

Response includes:

json

{
  "data": {
    "total": 100,
    "per_page": 50,
    "current_page": 2,
    "last_page": 2,
    "next_page_url": null,
    "prev_page_url": "...?page=1",
    "from": 51,
    "to": 100,
    "data": [...]
  }
}

Parameters:

• page - Page number (default: 1)
• limit - Results per page (default: 15)

Code Examples#

JavaScript#

javascript

const response = await fetch(
  'https://api.skillboss.com/v1/run',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SKILLBOSS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'prelude/notify-send',
      inputs: {
        template_id: 'your_template_id',
        to: '+15551234567',
        variables: { message: 'Hello from SkillBoss!' }
      }
    })
  }
);
const data = await response.json();
const result = data.result;
console.log(result);

Python#

python

import os
import requests

SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"]

response = requests.post(
    "https://api.skillboss.com/v1/run",
    headers={
        "Authorization": f"Bearer {SKILLBOSS_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "prelude/notify-send",
        "inputs": {
            "template_id": "your_template_id",
            "to": "+15551234567",
            "variables": {"message": "Hello from SkillBoss!"}
        }
    }
)
result = response.json()
print(result)

Notes#

• Phone numbers must be in E.164 format (e.g., +15551234567)
• All timestamps are Unix timestamps (seconds since epoch)
• Use source field to identify your application in analytics
• Templates support placeholders like {name}, {custom_1}, etc.
• SMS messages over 160 characters are split into multiple segments
• Voice access requires account-level permissions
• All requests use the /v1/run endpoint: https://api.skillboss.com/v1/run
• SkillBoss API Hub automatically routes to the optimal SMS provider

Error Handling#

StatusMeaning200Success400Bad request401Unauthorized - invalid credentials403Forbidden - insufficient permissions404Resource not found429Rate limited500Internal server error

Response codes:

• SUCCESS - Operation completed successfully
• FORBIDDEN - Access denied to resource
• BAD_REQUEST - Invalid request parameters
• INVALID_RECIPIENT - Invalid phone number

Troubleshooting: API Key Issues#

1. Check that the SKILLBOSS_API_KEY environment variable is set:

bash

echo $SKILLBOSS_API_KEY

1. Verify the API key is valid by making a test request:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.skillboss.com/v1/run')
req.add_header('Authorization', f'Bearer {os.environ["SKILLBOSS_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
import urllib.parse
data = json.dumps({'discover': True}).encode()
req.data = data
req.method = 'POST'
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resources#

• ClickSend Developer Portal
• ClickSend REST API v3 Documentation
• ClickSend PHP SDK
• ClickSend Help Center
• SkillBoss API Hub
• SkillBoss Support