API Reference

SMS API Overview

The SMS API allows you to send and receive SMS messages globally. It provides a simple and reliable way to integrate SMS messaging into your applications.

Base URL

All API requests should be made to the following base URL:

https://api.ovocommunications.com/v1

Authentication

All API requests require authentication using your API key. You can include your API key in the request headers as follows:

Authorization: Bearer YOUR_API_KEY

Endpoints

The SMS API provides the following endpoints:

{
  "message_id": "sm_1a2b3c4d5e6f7g8h9i0j",
  "status": "queued",
  "to": "+1234567890",
  "from": "OVO",
  "created_at": "2025-05-17T12:34:56Z"
}

{
  "batch_id": "batch_1a2b3c4d5e6f7g8h9i0j",
  "total_messages": 3,
  "successful": 3,
  "failed": 0,
  "messages": [
    {
      "message_id": "sm_1a2b3c4d5e6f7g8h9i0j",
      "status": "queued",
      "to": "+1234567890",
      "from": "OVO"
    },
    {
      "message_id": "sm_2b3c4d5e6f7g8h9i0j1k",
      "status": "queued",
      "to": "+2345678901",
      "from": "OVO"
    },
    {
      "message_id": "sm_3c4d5e6f7g8h9i0j1k2l",
      "status": "queued",
      "to": "+3456789012",
      "from": "OVO"
    }
  ],
  "created_at": "2025-05-17T12:34:56Z"
}

{
  "message_id": "sm_1a2b3c4d5e6f7g8h9i0j",
  "status": "delivered",
  "to": "+1234567890",
  "from": "OVO",
  "message": "Hello from OVO Communications!",
  "segments": 1,
  "created_at": "2025-05-17T12:34:56Z",
  "updated_at": "2025-05-17T12:35:10Z",
  "delivered_at": "2025-05-17T12:35:10Z"
}

Code Examples

Here are some examples of how to use the SMS API with different programming languages:

Python

import requests
import json

url = "https://api.ovocommunications.com/v1/sms/send"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "to": "+1234567890",
    "from": "OVO",
    "message": "Hello from OVO Communications!"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())

Node.js

const axios = require('axios');

const url = 'https://api.ovocommunications.com/v1/sms/send';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};
const data = {
  to: '+1234567890',
  from: 'OVO',
  message: 'Hello from OVO Communications!'
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

PHP

// Using cURL
$url = 'https://api.ovocommunications.com/v1/sms/send';
$data = json_encode([
    'to' => '+1234567890',
    'from' => 'OVO',
    'message' => 'Hello from OVO Communications!'
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data)
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of an API request. In general:

• 2xx: Success
• 4xx: Client error (e.g., invalid request, authentication error)
• 5xx: Server error

Error responses include a JSON object with details about the error:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'to' parameter must be a valid phone number in E.164 format.",
    "param": "to",
    "request_id": "req_1a2b3c4d5e6f7g8h9i0j"
  }
}