API Reference

API Reference

This API reference provides documentation for the SSDPortal API, allowing you to integrate SMS functionalities into your applications.

Getting Started

Before diving into the API details, you will need a few things:

API Key:

Obtain your API key by navigating to the “API” section within your SSDPortal account. You can generate a new key or manage existing ones.

Authentication:

SSDPortal utilizes basic authentication for API access. Include your API key in the Authorization header using the format “apikey”: “your_api_key”.

Base URL:

All API requests are made to the following base URL: https://ssdportal.com/api/v1

Endpoints

The SSDPortal API offers functionalities for managing users, contacts, and sending SMS messages. Here’s an overview of the key endpoints:

All endpoints require that you pass an API Key in the header.

User Management

  1. Endpoint: GET /users/ Description: Retrieves information about the currently authenticated user. It also shows the current available balance in USD. Sample Response:
{
    'status': 'success',
    'data': {
        'name': 'Deng',
        'email': 'dengdoe@gmail.com',
        'balance': 49.27
    }
}

Contact Management

  1. Endpoint: POST /contacts Description: Creates a new contact in your address book. Request Body (JSON):
{
    'name': 'Full Names',
    'phoneNumber': '+211920000000'
}
  • name: (String) Required. Name of the contact person or organization.
  • phoneNumber: (String) Required. Phone number of the contact in international format (e.g., +211912345678). Sample Response:
{
    'status': 'success',
    'data': {
        'id': 1,
        'name': 'Full names'
        'phone': '+211920000000',
        'isSupported': True,
        'updatedAt': 'date'
    }
}
  1. Endpoint: GET /contact Description: Retrieves a list of your existing contacts. Response: JSON array containing contact objects with details like name, phone number and if the phone number is supported. Sample Response:
{
    'status': 'success',
    'data': [
        {
            'id': 1,
            'name': 'Full names'
            'phone': '+211920000000',
            'isSupported': True,
            'updatedAt': '{date}'
        },
        ...
    ]
}
  1. Endpoint: GET /contacts/id Description: Retrieves specific details of a single contact by its ID. Path Parameter: id: (Integer) Required. Unique ID of the contact you want to retrieve. Response: JSON object containing the contact’s information.
{
    'status': 'success',
    'data': {
        'id': 1,
        'name': 'Full names'
        'phone': '+211920000000',
        'isSupported': True,
        'updatedAt': 'date'
    }
}
  1. Endpoint: PUT /contacts/id Description: Updates an existing contact’s information. Path Parameter: id: (Integer) Required. Unique ID of the contact you want to update. Request Body (JSON): Update any of the contact’s details mentioned in the POST /contacts endpoint.
{
    'name': 'Full Names',
    'phoneNumber': '+211920000000'
}

Sample Response:

{
    'status': 'success',
    'data': {
        'id': 1,
        'name': 'Full names'
        'phone': '+211920000000',
        'isSupported': True,
        'updatedAt': 'date'
    }
}

Messaging

  1. Endpoint: POST /messages Description: Sends an SMS message programmatically. Request Body (JSON):
{
    'template': 'OTP',
    'senderId': 'MyBrand',
    'phoneNumber': '+211920000000',
    'content': {
        'otp': 123456,
        'expiry_date': '2/10/2024 10:15'
    },
    'schedule': '2/10/2024 10:11'
}

phoneNumber: (String) Required. Recipient’s phone number in international format. senderId: (String) Required. Sender ID to use for the message (requires approved sender ID). content: (Object) Required. Content attributes of the SMS message. template (String) Required. Name of a pre-defined SMS template to use. schedule: (String) Optional. A date and time to schedule the delivery of the messages.

Response: JSON object containing information about the sent message, including its unique ID and status.

{
    'status': 'success',
    'data': {
        'message': parsedMessage,
        'messageId': messageId
    }
}

Rate Limits

Please note that SSDPortal enforces rate limits on API requests to prevent abuse. The specific limits may vary depending on your account plan. Be mindful of these limits and avoid sending excessive requests within a short timeframe.

API ManagementPython SDK