Guide Genetics SMS API Documentation

Complete integration guide and API reference

Home Admin

🚀 Quick Start

Guide Genetics SMS API - Developer Integration Guide

Overview

The Guide Genetics SMS API provides a simple REST API for sending SMS messages. Phone numbers are automatically configured per application, so you only need to specify the recipient and message content.

Base URL: https://sms.guidegenetics.com

Quick Start

1. Get API Credentials

Contact the administrator to:

  • Create an app for your service
  • Create an organization within the app
  • Generate an API key for your organization
  • Configure phone numbers for the app

2. Store Credentials

Save these in your application's environment variables:

bash
SMS_API_URL=https://sms.guidegenetics.com
SMS_API_KEY=your_api_key_here

3. Send Your First SMS

cURL Example:

bash
curl -X POST $SMS_API_URL/api/v1/sms/send \
  -H "Authorization: Bearer $SMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+1234567890", "message": "Hello from your app!"}'

Response:

json
{
  "success": true,
  "message_id": 123,
  "bird_message_id": "msg_abc123", 
  "status": "sent"
}

API Reference

Authentication

Use one of these methods:

Bearer Token (Recommended):

Authorization: Bearer YOUR_API_KEY

Custom Header:

X-API-Key: YOUR_API_KEY

Query Parameter:

?api_key=YOUR_API_KEY

Send SMS

Endpoint: POST /api/v1/sms/send

Request:

json
{
  "to": "+1234567890",    // Required: E.164 format phone number
  "message": "Your text"   // Required: Message content (max 1600 chars)
}

Success Response (201):

json
{
  "success": true,
  "message_id": 123,           // Internal message ID
  "bird_message_id": "msg_123", // Bird platform message ID
  "status": "sent"
}

Error Response (400/422):

json
{
  "error": "Invalid phone number format: 1234567890",
  "details": "Phone number must be in E.164 format (+1234567890)"
}

Get Message Status

Endpoint: GET /api/v1/sms/messages/:id

Response:

json
{
  "id": 123,
  "recipient": "+1234567890",
  "status": "sent",
  "error_message": null,
  "sent_at": "2025-08-14T10:30:00Z",
  "created_at": "2025-08-14T10:29:58Z"
}

List Messages

Endpoint: GET /api/v1/sms/messages

Query Parameters:

  • page - Page number (default: 1)
  • per_page - Messages per page (default: 20, max: 100)
  • status - Filter by status: pending, sent, delivered, failed

Response:

json
{
  "messages": [...],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 95
  }
}

Get Available Phone Numbers (Optional)

Endpoint: GET /api/v1/sms/from-numbers

Response:

json
{
  "app_name": "Your App Name",
  "phone_numbers": [
    {
      "number": "+18882127786",
      "label": "Primary SMS",
      "channel_id": "ce1de3ed-3fb0-439c-b5e8-94a95aa8e6ae"
    }
  ],
  "default_from_number": "+18882127786"
}

Note: This endpoint is optional. Phone numbers are automatically selected when sending SMS.

Code Examples

Ruby

ruby
require 'httparty'

class SmsService
  def initialize(api_url, api_key)
    @api_url = api_url
    @api_key = api_key
  end

  def send_sms(to, message)
    response = HTTParty.post(
      "#{@api_url}/api/v1/sms/send",
      headers: {
        'Authorization' => "Bearer #{@api_key}",
        'Content-Type' => 'application/json'
      },
      body: { to: to, message: message }.to_json
    )

    if response.success?
      JSON.parse(response.body)
    else
      { error: response.body }
    end
  end
end

# Usage
sms = SmsService.new(ENV['SMS_API_URL'], ENV['SMS_API_KEY'])
result = sms.send_sms('+1234567890', 'Hello from Ruby!')
puts result

Node.js

javascript
const axios = require('axios');

class SmsService {
  constructor(apiUrl, apiKey) {
    this.apiUrl = apiUrl;
    this.apiKey = apiKey;
  }

  async sendSms(to, message) {
    try {
      const response = await axios.post(`${this.apiUrl}/api/v1/sms/send`, {
        to: to,
        message: message
      }, {
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        }
      });

      return response.data;
    } catch (error) {
      return { error: error.response?.data || error.message };
    }
  }
}

// Usage
const sms = new SmsService(process.env.SMS_API_URL, process.env.SMS_API_KEY);
sms.sendSms('+1234567890', 'Hello from Node.js!')
   .then(result => console.log(result));

Python

python
import requests
import os

class SmsService:
    def __init__(self, api_url, api_key):
        self.api_url = api_url
        self.api_key = api_key

    def send_sms(self, to, message):
        try:
            response = requests.post(
                f"{self.api_url}/api/v1/sms/send",
                headers={'Authorization': f'Bearer {self.api_key}'},
                json={'to': to, 'message': message}
            )
            return response.json()
        except Exception as e:
            return {'error': str(e)}

# Usage
sms = SmsService(os.environ['SMS_API_URL'], os.environ['SMS_API_KEY'])
result = sms.send_sms('+1234567890', 'Hello from Python!')
print(result)

PHP

php
<?php

class SmsService {
    private $apiUrl;
    private $apiKey;

    public function __construct($apiUrl, $apiKey) {
        $this->apiUrl = $apiUrl;
        $this->apiKey = $apiKey;
    }

    public function sendSms($to, $message) {
        $data = json_encode([
            'to' => $to,
            'message' => $message
        ]);

        $options = [
            'http' => [
                'header' => [
                    'Authorization: Bearer ' . $this->apiKey,
                    'Content-Type: application/json'
                ],
                'method' => 'POST',
                'content' => $data
            ]
        ];

        $context = stream_context_create($options);
        $result = file_get_contents($this->apiUrl . '/api/v1/sms/send', false, $context);

        return json_decode($result, true);
    }
}

// Usage
$sms = new SmsService($_ENV['SMS_API_URL'], $_ENV['SMS_API_KEY']);
$result = $sms->sendSms('+1234567890', 'Hello from PHP!');
print_r($result);
?>

Error Handling

HTTP Status Codes

  • 200 OK: Request successful
  • 201 Created: SMS sent successfully
  • 400 Bad Request: Missing or invalid parameters
  • 401 Unauthorized: Invalid API key
  • 422 Unprocessable Entity: Invalid phone number or Bird API error
  • 500 Internal Server Error: Server error

Common Errors

json
// Missing parameters
{
  "error": "Recipient and message are required"
}

// Invalid phone number
{
  "error": "Invalid phone number format: 1234567890",
  "details": "Phone number must be in E.164 format (+1234567890)"
}

// Bird API error  
{
  "error": "Rate limit exceeded"
}

// Invalid API key
{
  "error": "Invalid API key"
}

Error Handling Best Practices

  1. Always check response status before processing
  2. Handle rate limits with exponential backoff
  3. Validate phone numbers before sending
  4. Log errors for debugging
  5. Implement retry logic for transient errors

Testing

Postman Setup

  1. URL: https://sms.guidegenetics.com/api/v1/sms/send
  2. Method: POST
  3. Authorization Tab: Bearer Token → [Your API Key]
  4. Body Tab: raw → JSON json { "to": "+1234567890", "message": "Test SMS from Postman!" }

Test Phone Numbers

For testing, you can use any valid phone number format, but make sure:

  • Use E.164 format: +1234567890
  • Include country code
  • No spaces or special characters

FAQ

Q: Do I need to specify a FROM_NUMBER? A: No! Phone numbers are automatically configured per app. Just specify to and message.

Q: What phone number will be used to send SMS?
A: Use GET /api/v1/sms/from-numbers to see which phone number your app uses.

Q: How do I handle delivery receipts? A: Currently, message status is tracked internally. Use GET /api/v1/sms/messages/:id to check delivery status.

Q: What's the message length limit? A: 1600 characters maximum. For best delivery rates, keep under 160 characters.

Q: How do I handle international numbers? A: Always use E.164 format with country code (e.g., +441234567890 for UK).

Q: Can I send to multiple recipients? A: Make separate API calls for each recipient to ensure proper tracking.

Support

For technical issues or questions:

  1. Check error messages in API responses
  2. Review this documentation
  3. Contact the API administrator for account-related issues

Rate Limits

  • 1000 requests per hour per API key
  • 100 requests per minute burst limit
  • Custom limits available on request

Security

  • Always use HTTPS in production
  • Store API keys securely as environment variables
  • Never commit API keys to version control
  • Rotate API keys periodically

Need Help?

If you have questions or need assistance with the API integration, we're here to help.

Email Support