API Reference

Common Patterns

Cursor Pagination

All list endpoints return paginated results with the same envelope. Pass the cursor value from the previous response to fetch the next page. limit defaults to 20 (capped at 10 for API key authentication).

{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "nextCursor": "MjAyNS0wNi0xNVQxMjowMDowMC4wMDBafGFiY2QxMjM0",
    "total": 42,
    "limit": 20
  }
}

Error Format

Errors follow a consistent JSON structure across all endpoints.

{
  "error": "NOT_FOUND",
  "message": "Number not found or you do not have access"
}

API Key Scopes

API keys can be scoped to personal/team numbers, selected numbers, or one enterprise contract. Scoped keys filter GET /v1/numbers and GET /v1/messages. Existing keys created before scoped keys behave as personal keys.

{
  "scopeType": "ENTERPRISE_CONTRACT",
  "enterpriseContractId": "contract_uuid_here"
}

API Key Capabilities

Sensitive write capabilities are opt-in at API key creation. SMS replies require the sms:reply capability in addition to the key's normal number scope. Existing keys do not receive this capability automatically.

{
  "capabilities": ["sms:reply"]
}

Rate Limit Headers

Every response includes rate limit headers. API key requests are limited to 120 requests per minute.

API Key Management

Create and revoke API keys from a logged-in browser session. API keys are shown once at creation time and can be scoped to personal/team numbers, selected numbers, or an enterprise contract.

Create an enterprise contract key

curl -X POST "https://api.joltsms.com/v1/api-keys" \
  -H "Content-Type: application/json" \
  -H "Cookie: joltsms_session=..." \
  -d '{
    "name": "Enterprise contract automation",
    "scopeType": "ENTERPRISE_CONTRACT",
    "enterpriseContractId": "contract_uuid_here"
  }'

Response

{
  "key": "jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "id": "api_key_uuid",
  "name": "Enterprise contract automation",
  "prefix": "jolt_sk_a1b2c3d4",
  "scopeType": "ENTERPRISE_CONTRACT",
  "enterpriseContractId": "contract_uuid_here",
  "enterpriseContractName": "Example Enterprise",
  "numberScopeCount": 0,
  "numberScopes": [],
  "capabilities": [],
  "expiresAt": null,
  "createdAt": "2026-06-17T18:00:00.000Z"
}

Numbers

Manage your dedicated phone numbers. Each number is a real-SIM U.S. number that receives inbound SMS. API-key requests are filtered by the key's scope.

Example

curl -X GET "https://api.joltsms.com/v1/numbers?scope=owned&status=active" \
  -H "Authorization: Bearer jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Response:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phoneNumber": "+16094130666",
      "status": "ACTIVE",
      "serviceName": "Any Service",
      "tags": ["primary", "otp"],
      "notes": "Used for PayPal verification",
      "createdAt": "2025-06-15T12:00:00.000Z",
      "rentedAt": "2025-06-15T12:05:00.000Z",
      "expiresAt": "2025-07-15T12:05:00.000Z",
      "messageCount": 23,
      "unreadCount": 2,
      "lastMessageAt": "2025-06-20T08:30:00.000Z",
      "isShared": false,
      "accessRole": "OWNER"
    }
  ],
  "meta": {
    "hasMore": false,
    "total": 1,
    "limit": 20
  }
}

Messages

Read inbound SMS messages across all your numbers (owned and shared), and reply to eligible inbound SMS conversations. API-key requests are filtered by the key's scope. Messages from vendor systems are automatically filtered out.

Example

curl -X GET "https://api.joltsms.com/v1/messages?numberId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=5" \
  -H "Authorization: Bearer jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Reply example

curl -X POST "https://api.joltsms.com/v1/messages/f1e2d3c4-b5a6-7890-1234-567890abcdef/reply" \
  -H "Authorization: Bearer jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: reply-f1e2d3c4-001" \
  -d '{"content":"Thanks, received."}'

Reply response:

{
  "success": true,
  "replyId": "0f5c6a5b-5b8f-45f4-9d2f-491a5d00f093",
  "messageId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "status": "SENT",
  "sentAt": "2026-06-19T18:30:00.000Z",
  "correlationId": "req_abc123",
  "message": "Reply sent."
}

Response:

{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "numberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "number": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "phoneNumber": "+16094130666"
      },
      "from": "+18005551234",
      "to": "+16094130666",
      "body": "Your verification code is 847293. Do not share this with anyone.",
      "parsedCode": "847293",
      "isRead": false,
      "receivedAt": "2025-06-20T08:30:00.000Z",
      "ingestedAt": "2025-06-20T08:30:01.000Z"
    }
  ],
  "meta": {
    "hasMore": false,
    "nextCursor": null,
    "total": 1,
    "limit": 5,
    "filters": {
      "numberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

Billing

Inspect subscriptions, invoices, and payment methods. Billing is handled through Stripe with 30-day cycles aligned to your SMS provider.

Example

curl -X POST "https://api.joltsms.com/v1/billing/subscriptions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/auto-renew" \
  -H "Authorization: Bearer jolt_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Response:

{
  "success": true
}

Notifications

Configure multi-channel notification delivery for SMS events, billing alerts, and number lifecycle changes. Supported channels: Slack, Discord, Email, Telegram, and custom Webhooks (HMAC-SHA256 signed).

Endpoints

Rules

Rules bind events to endpoints. You can create account-level defaults or per-number overrides. Limits: 15 endpoints per user, 10 rules per number.

Delivery Logs

Team

Share number access with other JoltSMS users. Invite team members with VIEWER (read-only) or MANAGER (configuration and team management) roles. Invitations expire after 7 days.

Example

curl -X POST "https://api.joltsms.com/v1/team/invite" \
  -H "Cookie: better-auth.session_token=..." \
  -H "Content-Type: application/json" \
  -d '{ "numberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "[email protected]", "role": "VIEWER" }'

Response:

{
  "success": true,
  "invitationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Invitation sent successfully"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the outcome of each request.