Getting Started

Welcome to the Approved Contact Texting API! This guide will walk you through the basics of setting up your account and sending your first message in just a few minutes.

Time to Complete: 10 minutes
Difficulty: Beginner

Prerequisites

Before you begin, make sure you have:

An Approved Contact account - Sign up at approvedcontact.com
API Credentials - Your username (email) and password for Basic Authentication
A provisioned phone number - At least one phone number to send messages from

Important: Keep your API credentials secure. Never expose them in client-side code or public repositories. Store them in environment variables or secure credential management systems.

Authentication

The Approved Contact API uses HTTP Basic Authentication. You'll need to encode your credentials (username:password) in Base64 and include them in the Authorization header of every request.

Encoding Your Credentials

Here's how to create your authentication header:

# Using curl, Base64 encoding is done automatically
USERNAME="your-email@example.com"
PASSWORD="your-password"

curl -X POST https://api.approvedcontact.com/api/v1/messages \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"from": "+15551234567", "to": ["+15559876543"], "body": "Test message"}'

import base64
import requests

username = "your-email@example.com"
password = "your-password"

# Encode credentials
credentials = base64.b64encode(f"{username}:{password}".encode()).decode()

headers = {
    "Authorization": f"Basic {credentials}",
    "Content-Type": "application/json"
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var username = "your-email@example.com";
var password = "your-password";

// Encode credentials
var credentials = Convert.ToBase64String(
    Encoding.ASCII.GetBytes($"{username}:{password}"));

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Basic", credentials);

const username = 'your-email@example.com';
const password = 'your-password';

// Encode credentials
const credentials = Buffer.from(`${username}:${password}`).toString('base64');

const headers = {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
};

Send Your First Message

Now that you have your authentication set up, let's send a simple SMS message. You'll need:

from - Your provisioned phone number (E.164 format: +1XXXXXXXXXX)
to - Array of recipient phone numbers (E.164 format)
body - The message text (up to 1600 characters)

Example: Send a Simple SMS

curl -X POST https://api.approvedcontact.com/api/v1/messages \
  -u "your-email@example.com:your-password" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543"],
    "body": "Hello! This is my first message from the Approved Contact API."
  }'

import requests
import base64

username = "your-email@example.com"
password = "your-password"
credentials = base64.b64encode(f"{username}:{password}".encode()).decode()

url = "https://api.approvedcontact.com/api/v1/messages"

headers = {
    "Authorization": f"Basic {credentials}",
    "Content-Type": "application/json"
}

payload = {
    "from": "+15551234567",
    "to": ["+15559876543"],
    "body": "Hello! This is my first message from the Approved Contact API."
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    result = response.json()
    print(f"Message sent! ID: {result.get('messageId')}")
else:
    print(f"Error: {response.status_code} - {response.text}")

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        var username = "your-email@example.com";
        var password = "your-password";
        var credentials = Convert.ToBase64String(
            Encoding.ASCII.GetBytes($"{username}:{password}"));

        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Basic", credentials);

        var payload = new
        {
            from = "+15551234567",
            to = new[] { "+15559876543" },
            body = "Hello! This is my first message from the Approved Contact API."
        };

        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            "https://api.approvedcontact.com/api/v1/messages", 
            content);

        if (response.IsSuccessStatusCode)
        {
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Message sent! Response: {result}");
        }
        else
        {
            Console.WriteLine($"Error: {response.StatusCode}");
        }
    }
}

const axios = require('axios');

const username = 'your-email@example.com';
const password = 'your-password';
const credentials = Buffer.from(`${username}:${password}`).toString('base64');

const url = 'https://api.approvedcontact.com/api/v1/messages';

const headers = {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
};

const payload = {
    from: '+15551234567',
    to: ['+15559876543'],
    body: 'Hello! This is my first message from the Approved Contact API.'
};

axios.post(url, payload, { headers })
    .then(response => {
        console.log('Message sent!', response.data);
    })
    .catch(error => {
        console.error('Error:', error.response?.data || error.message);
    });

Response

A successful response will look like this:

{
  "messageId": "msg_abc123def456",
  "from": "+15551234567",
  "to": ["+15559876543"],
  "body": "Hello! This is my first message from the Approved Contact API.",
  "status": "queued",
  "createdAt": "2025-01-11T10:30:00Z",
  "segments": 1,
  "cost": 0.0075
}

Congratulations! You've successfully sent your first message using the Approved Contact API. The message is now queued for delivery.

Next Steps

Now that you've sent your first message, here are some recommended next steps:

Additional Resources

Complete API Reference - Detailed documentation of all endpoints
Authentication Guide - Deep dive into authentication and security
Troubleshooting - Common issues and solutions

Need Help?
If you run into any issues or have questions, contact our support team at support@approvedcontact.com