Developer Quick Start

Developer Quick Start

This guide takes you from zero to a working integration: mint an API key, send an SMS from your code, then receive a webhook when its delivery status changes. Budget about 10 minutes.

Prerequisites

• A SIPSTACK organization on a plan that includes API access (API access is plan-gated).
• At least one active SMS-capable number on your account.
• A tool to receive an HTTPS POST — webhook.site or ngrok works for testing.

Step 1 — Get an API key

An owner or admin on your organization mints a key in Switchboard at Account → Integrations → API keys — set a name, pick scopes, and choose an expiry. Prefer to script it? Create one through the management API with an owner portal session:

curl -s -X POST https://api.sipstack.com/api/api-keys \
  -H "Authorization: Bearer <owner-portal-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Quick Start", "environment": "production" }'

The full key (sk_live_...) is returned only at creation (in the UI or the response above) — copy it now. See API Keys for scopes, expiry, and the full lifecycle.

Tip

Confirm the key works with a no-op identity call: curl -H "x-api-key: sk_live_..." https://api.sipstack.com/api/v2/me returns your organization id.

Step 2 — Send an SMS

curl -s -X POST https://api.sipstack.com/api/v2/messages/send \
  -H "x-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14165550100",
    "message": "Hello from SIPSTACK 👋"
  }'

A 200 with "status": "sent" means the carrier accepted it. Omit from to use your first active number. Sending goes through Flare (SIPSTACK’s transactional / A2P messaging product) — see API Overview for how Flare and Nova SMS differ.

Step 3 — Receive a webhook

Register an endpoint so SIPSTACK notifies you when the message is delivered:

curl -s -X POST https://api.sipstack.com/api/v2/webhooks \
  -H "x-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-endpoint.example.com/sipstack",
    "events": ["message.delivered", "message.failed"]
  }'

The response returns a signing secret, shown only once — store it. When the carrier confirms delivery, SIPSTACK POSTs a message.delivered event to your URL with an X-Webhook-Signature header you verify against that secret.

Verify it end to end: fire a test delivery to your endpoint on demand, then send another SMS and watch the real message.delivered arrive:

# one-off connectivity/signature check (portal session)
curl -s -X POST https://api.sipstack.com/api/webhooks/<id>/test \
  -H "Authorization: Bearer <owner-portal-session-jwt>"

See the full Webhooks guide for the event catalog, payload shapes, signature verification code, and retry behavior.

Where to go next

• API Overview — the full Developer API surface: Flare (messages, contacts), Nova (calling, voicemails), Aura (agent calls), and webhooks
• API Reference — request/response shapes for every endpoint
• Authentication — API keys and portal sessions
• Webhooks — events, signatures, and delivery behavior