SMS Logs

SMS logging is essential for monitoring messaging activity, delivery tracking, and compliance requirements. On this page, we will dive into the SMS logging endpoints you can use to retrieve and analyze SMS records programmatically. We will look at how to fetch SMS logs with filtering and export functionality.

The SMS log model

The SMS log model contains detailed information about individual SMS messages, including content, delivery status, and cost calculations.

Properties

Name
log_id
Type
uuid
Description
Unique identifier for the SMS log entry.
Name
virtual_number_id
Type
uuid
Description
The virtual number used for the SMS.
Name
customer_id
Type
uuid
Description
Customer identifier owning the SMS record.
Name
sms_direction
Type
string
Description
SMS direction: "inbound" or "outbound".
Name
from_number
Type
string
Description
Originating phone number.
Name
to_number
Type
string
Description
Destination phone number.
Name
message_body
Type
string
Description
SMS message content (nullable).
Name
sms_status
Type
string
Description
Delivery status (e.g., "delivered", "pending", "failed").
Name
sent_at
Type
timestamp
Description
Message sent timestamp.
Name
delivered_at
Type
timestamp
Description
Message delivery timestamp (nullable).
Name
segment_count
Type
integer
Description
Number of SMS segments used (nullable).
Name
provider_sms_id
Type
string
Description
Provider's unique identifier for the SMS (nullable).
Name
cost_per_sms
Type
decimal
Description
Cost per SMS message (nullable).
Name
total_cost
Type
decimal
Description
Total calculated cost for the SMS (nullable).
Name
currency
Type
string
Description
Currency for cost calculations (nullable).
Name
provider_name
Type
string
Description
Name of the SMS provider (nullable).
Name
created_at
Type
timestamp
Description
Record creation timestamp.
Name
updated_at
Type
timestamp
Description
Last record update timestamp.

GET/customers/{customerSlug}/logs/sms

List SMS logs

This endpoint allows you to retrieve SMS logs for your customer account with comprehensive filtering and sorting options. By default, a maximum of ten records are shown per page.

Optional attributes

Name
page
Type
integer
Description
Page number for pagination (default: 1, min: 1).
Name
limit
Type
integer
Description
Number of logs per page (default: 10, min: 1, max: 100).
Name
search
Type
string
Description
General search string to filter logs.
Name
virtual_number_id
Type
uuid
Description
Filter by specific virtual number ID.
Name
sms_direction
Type
string
Description
Filter by SMS direction: "inbound" or "outbound".
Name
sms_status
Type
string
Description
Filter by SMS status.
Name
start_date
Type
string
Description
Filter logs from this date (ISO 8601 format).
Name
end_date
Type
string
Description
Filter logs until this date (ISO 8601 format).
Name
sort_by
Type
string
Description
Sort field: "sent_at", "segment_count", "total_cost" (default: "sent_at").
Name
sort_order
Type
string
Description
Sort direction: "asc" or "desc" (default: "desc").

Request

GET

/logs/sms

curl -G https://api.xnumbers.io/customers/acme-corp/logs/sms \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=10 \
  -d sms_direction=outbound \
  -d start_date=2024-01-01 \
  -d sort_by=sent_at \
  -d sort_order=desc

Response

{
  "data": [
    {
      "log_id": "12345678-1234-1234-1234-123456789abc",
      "virtual_number_id": "87654321-4321-4321-4321-210987654321",
      "customer_id": "11111111-1111-1111-1111-111111111111",
      "sms_direction": "outbound",
      "from_number": "+12125551234",
      "to_number": "+15559876543",
      "message_body": "Your verification code is: 123456",
      "sms_status": "delivered",
      "sent_at": "2024-01-15T10:30:00.000Z",
      "delivered_at": "2024-01-15T10:30:02.000Z",
      "segment_count": 1,
      "provider_sms_id": "prov_sms_789123",
      "cost_per_sms": 0.01,
      "total_cost": 0.01,
      "currency": "USD",
      "provider_name": "SMS Provider Inc",
      "created_at": "2024-01-15T10:30:03.000Z",
      "updated_at": "2024-01-15T10:30:03.000Z"
    }
  ],
  "meta": {
    "total": 250,
    "page": 1,
    "limit": 10,
    "totalPages": 25,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

GET/customers/{customerSlug}/logs/sms/export

Export SMS logs

This endpoint allows you to export SMS logs as a CSV file. The export includes all the same filtering options as the list endpoint but returns the data in CSV format for download.

Optional attributes

All the same query parameters from the list endpoint are supported for filtering the exported data.

Export Format

The CSV export includes all SMS log fields with proper headers and formatting for analysis in spreadsheet applications.

Request

GET

/logs/sms/export

curl -G https://api.xnumbers.io/customers/acme-corp/logs/sms/export \
  -H "Authorization: Bearer {token}" \
  -d sms_direction=outbound \
  -d start_date=2024-01-01 \
  -d end_date=2024-01-31 \
  --output sms_logs.csv

Returns the CSV file as a download with appropriate headers:

Content-Type: text/csv
Content-Disposition: attachment; filename="sms_logs.csv"