Examples

This page collects copy-paste-ready examples using the canonical test values:

• client_id = rc_test_client_123
• client_secret = rc_secret_abc123
• access_token = rc_token_example
• numberId = num_abc123
• messageId = msg_abc123
• externalReference = order_789
• phone = +15551234567

Curl examples

Step 1: Token request with HTTP Basic auth

Request

curl -X POST "$BASE_URL/api/auth/token" \
  -u "rc_test_client_123:rc_secret_abc123" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Response

{
  "access_token": "rc_token_example",
  "token_type": "bearer",
  "expires_in": 3600
}

Step 2: Whoami

Request

curl "$BASE_URL/api/core/whoami" \
  -H "Authorization: Bearer rc_token_example"

Response

{
  "apiClientId": "rc_test_client_123",
  "apiClientName": "Red Cloud Test Client",
  "apiClientStatus": "ACTIVE",
  "capabilities": [
    "numbers:read",
    "numbers:search",
    "numbers:update"
  ],
  "assignedNumbers": {
    "total": 1,
    "smsEnabledCount": 1,
    "mmsEnabledCount": 1
  },
  "inboundWebhookConfigured": true,
  "deliveryWebhookConfigured": true
}

Step 3: List numbers

Request

curl "$BASE_URL/api/core/numbers" \
  -H "Authorization: Bearer rc_token_example"

Response

{
  "numbers": [
    {
      "numberId": "num_abc123",
      "e164": "+15551234567",
      "status": "ACTIVE",
      "campaignRegId": "A1B2C3",
      "smsEnabled": true,
      "mmsEnabled": true,
      "webhookInboundOverride": "https://example.com/webhooks/inbound",
      "webhookDeliveryOverride": "https://example.com/webhooks/delivery"
    }
  ]
}

Step 4: Send message

Request

curl -X POST "$BASE_URL/api/core/messages/send" \
  -H "Authorization: Bearer rc_token_example" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_order_789" \
  -d '{
    "sendFrom": "num_abc123",
    "to": ["+15551234567"],
    "messageType": "SMS",
    "text": "Hello from Red Cloud",
    "externalReference": "order_789"
  }'

Response

{
  "results": [
    {
      "to": "+15551234567",
      "messageId": "msg_abc123",
      "status": "QUEUED"
    }
  ],
  "errors": []
}

JavaScript example (Node.js)

The script below:

1. gets a token
2. calls /api/core/whoami
3. sends a message

Request

const baseUrl = process.env.RC_BASE_URL;
const clientId = process.env.RC_CLIENT_ID ?? "rc_test_client_123";
const clientSecret = process.env.RC_CLIENT_SECRET ?? "rc_secret_abc123";
const numberId = process.env.RC_NUMBER_ID ?? "num_abc123";
const recipient = process.env.RC_TO ?? "+15551234567";

if (!baseUrl) {
  throw new Error("Set RC_BASE_URL before running this script.");
}

async function getToken() {
  const basic = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
  const response = await fetch(`${baseUrl}/api/auth/token`, {
    method: "POST",
    headers: {
      Authorization: `Basic ${basic}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: new URLSearchParams({
      grant_type: "client_credentials",
    }),
  });

  if (!response.ok) {
    throw new Error(`Token request failed: ${response.status} ${await response.text()}`);
  }

  return response.json();
}

async function callWhoami(accessToken) {
  const response = await fetch(`${baseUrl}/api/core/whoami`, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  if (!response.ok) {
    throw new Error(`whoami failed: ${response.status} ${await response.text()}`);
  }

  return response.json();
}

async function sendMessage(accessToken) {
  const response = await fetch(`${baseUrl}/api/core/messages/send`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "idem_order_789",
    },
    body: JSON.stringify({
      sendFrom: numberId,
      to: [recipient],
      messageType: "SMS",
      text: "Hello from Red Cloud",
      externalReference: "order_789",
    }),
  });

  if (!response.ok) {
    throw new Error(`send failed: ${response.status} ${await response.text()}`);
  }

  return response.json();
}

const token = await getToken();
console.log("Token response:", token);

const whoami = await callWhoami(token.access_token);
console.log("Whoami response:", whoami);

const send = await sendMessage(token.access_token);
console.log("Send response:", send);

Explanation

Run this with environment variables:

export RC_BASE_URL="https://your-red-cloud-host"
export RC_CLIENT_ID="rc_test_client_123"
export RC_CLIENT_SECRET="rc_secret_abc123"
export RC_NUMBER_ID="num_abc123"
export RC_TO="+15551234567"
node quickstart.js

sendFrom must remain a number id. Do not replace it with an E.164 phone number.

Python example

The script below performs the same core flow:

1. gets a token
2. confirms client context with /api/core/whoami
3. lists assigned numbers
4. sends a message

Request

import base64
import json
import os
import urllib.error
import urllib.parse
import urllib.request

BASE_URL = os.environ["RC_BASE_URL"]
CLIENT_ID = os.environ.get("RC_CLIENT_ID", "rc_test_client_123")
CLIENT_SECRET = os.environ.get("RC_CLIENT_SECRET", "rc_secret_abc123")
NUMBER_ID = os.environ.get("RC_NUMBER_ID", "num_abc123")
RECIPIENT = os.environ.get("RC_TO", "+15551234567")


def request(method, path, headers=None, body=None):
    req = urllib.request.Request(
        f"{BASE_URL}{path}",
        method=method,
        headers=headers or {},
        data=body,
    )
    try:
        with urllib.request.urlopen(req) as response:
            return json.loads(response.read().decode("utf-8"))
    except urllib.error.HTTPError as exc:
        raise RuntimeError(f"{method} {path} failed: {exc.code} {exc.read().decode('utf-8')}")


def get_token():
    basic = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode("utf-8")).decode("utf-8")
    body = urllib.parse.urlencode({"grant_type": "client_credentials"}).encode("utf-8")
    return request(
        "POST",
        "/api/auth/token",
        headers={
            "Authorization": f"Basic {basic}",
            "Content-Type": "application/x-www-form-urlencoded",
        },
        body=body,
    )


def get_whoami(access_token):
    return request(
        "GET",
        "/api/core/whoami",
        headers={"Authorization": f"Bearer {access_token}"},
    )


def list_numbers(access_token):
    return request(
        "GET",
        "/api/core/numbers",
        headers={"Authorization": f"Bearer {access_token}"},
    )


def send_message(access_token):
    body = json.dumps(
        {
            "sendFrom": NUMBER_ID,
            "to": [RECIPIENT],
            "messageType": "SMS",
            "text": "Hello from Red Cloud",
            "externalReference": "order_789",
        }
    ).encode("utf-8")

    return request(
        "POST",
        "/api/core/messages/send",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "idem_order_789",
        },
        body=body,
    )


token = get_token()
print("Token response:", token)

whoami = get_whoami(token["access_token"])
print("Whoami response:", whoami)

numbers = list_numbers(token["access_token"])
print("Numbers response:", numbers)

send = send_message(token["access_token"])
print("Send response:", send)

Explanation

Run this with environment variables:

export RC_BASE_URL="https://your-red-cloud-host"
export RC_CLIENT_ID="rc_test_client_123"
export RC_CLIENT_SECRET="rc_secret_abc123"
export RC_NUMBER_ID="num_abc123"
export RC_TO="+15551234567"
python3 quickstart.py

Example usage notes

Keep these rules consistent across all languages:

• acquire a fresh token before debugging deeper failures
• call /api/core/whoami before assuming the client context is correct
• use numberId for sendFrom
• include Idempotency-Key on every send
• treat 202 and QUEUED as acceptance, not final delivery
• use webhook events to observe the later lifecycle

Related pages

• Quickstart
• Authentication
• Numbers
• Sending Messages
• Idempotency and Retries