REST API Guide

← Back to Main Documentation

This guide provides comprehensive documentation for the OmniSS7 REST API and Swagger UI.

Table of Contents

1. Overview
2. HTTP Server Configuration
3. Swagger UI
4. API Endpoints
5. Worked Examples
6. Authentication
7. Response Formats
8. Error Handling
9. Metrics (Prometheus)
10. Example Requests

---

Overview

OmniSS7 exposes a REST API on port 8080 for driving MAP (Mobile Application Part) and CAP (CAMEL Application Part) operations over the SS7 network, plus raw SCCP/M3UA injection for testing. The API handler (APIhandler, lib/ss7_web/apihandler.ex) defines 47 POST /api/* operation endpoints alongside the metrics and Swagger endpoints. It allows you to:

• Trigger MAP requests (mobility, SMS, authentication, subscriber data, supplementary services, location services, GPRS, equipment)
• Drive CAP/CAMEL call-control dialogues
• Inject raw SCCP/M3UA payloads
• Monitor system metrics via Prometheus

For per-operation request/response schemas and MAP opcodes, this guide cross-references the MAP Client Guide, which documents every operation in detail.

Ports and Transports

OmniSS7 runs three distinct HTTP servers. This guide covers the first one (:8080). The others are documented in the Configuration Reference.

Port	Transport	Server	Scope of this guide
8080	HTTP — Plug.Cowboy	APIhandler	Yes — MAP/CAP REST /api/*, /metrics, /swagger.
8087	HTTPS — Bandit (Phoenix)	ControlPanelWeb.Endpoint	No — web control panel UI. See Web UI Guide.
8445	HTTPS / TLS	:api_ex REST controllers	No — status/routing/links REST. See Configuration Reference.

API Architecture

---

HTTP Server Configuration

Server Details

The /api/*, /metrics, and /swagger endpoints are served by a Plug.Cowboy HTTP listener (lib/application.ex).

Parameter	Value	Configurable
Protocol	HTTP	No
IP Address	0.0.0.0 (all interfaces)	Via code only
Port	8080	Via code only
Transport	Plug.Cowboy	No

Access URL: http://[server-ip]:8080

The control panel (:8087, Bandit) and the :api_ex REST controllers (:8445, TLS) are separate servers — see Ports and Transports.

Enabling/Disabling the HTTP Server

Control whether the :8080 HTTP server starts:

config :omniss7,
  start_http_server: true  # Set to false to disable

Default: true (enabled)

When Disabled: The :8080 HTTP server will not start, and the REST API / Swagger UI / metrics endpoint will be unavailable. The control panel (:8087) and :api_ex (:8445) servers are unaffected (they are gated by start_web_interfaces).

---

Swagger UI

The API includes a Swagger UI for interactive API documentation and testing.

Accessing Swagger UI

URL: http://[server-ip]:8080/swagger

Features:

• Interactive API documentation
• Try-it-out functionality for testing endpoints
• Request/response schemas
• Example payloads

Swagger JSON

The OpenAPI specification is available at:

URL: http://[server-ip]:8080/swagger.json

Use Cases:

• Import into Postman or other API clients
• Generate client libraries
• API documentation automation

---

API Endpoints

Every operation endpoint follows the pattern POST /api/{operation} and accepts a JSON request body. Requests are synchronous: the handler blocks until the SS7 response arrives or the operation times out (default 10 seconds for awaited MAP operations — see Error Handling).

The tables below list all 47 operation endpoints grouped by category. For each operation's request fields, response schema, and MAP opcode, see the corresponding section of the MAP Client Guide, which was refreshed alongside this guide and documents every operation in full.

Response codes (all endpoints): 200 = success, 400 = bad/invalid request (missing or wrong-typed fields), 504 = timeout (no SS7 response within the operation's timeout), 500 = operation error (non-timeout), 503 = feature not enabled (USSD), 404 = unknown path. See Error Handling.

Mobility Management

Operation	Endpoint	Description
Update Location	POST /api/updateLocation	Register a subscriber's serving VLR with the HLR. In HLR mode this triggers the InsertSubscriberData (ISD) sequence.
Cancel Location	POST /api/cancelLocation	Instruct a VLR to delete a subscriber record.
Provide Roaming Number	POST /api/prn	Obtain an MSRN from the serving MSC.
Purge MS	POST /api/purgeMS	Mark a subscriber as purged at the HLR.
Send Identification	POST /api/sendIdentification	Retrieve IMSI/auth data from the previous VLR (TMSI supplied as hex).
Reset	POST /api/reset	HLR-initiated reset toward a VLR (unconfirmed — returns {"status":"sent"}).
Restore Data	POST /api/restoreData	VLR requests subscriber-data restoration from the HLR.

SMS

Operation	Endpoint	Description
Send Routing Info for SM	POST /api/sri-for-sm	Query the HLR for the serving node for SMS delivery.
MT-Forward SM	POST /api/MT-forwardSM	Deliver a mobile-terminated SM to the serving MSC/SGSN (smsPDU as hex).
MO-Forward SM	POST /api/forwardSM	Submit a mobile-originated SM (smsPDU as hex).
Send SM	POST /api/sendSM	Build and deliver an SMS-DELIVER from GSM-7 text.
Build Deliver PDU	POST /api/deliverPDU	Build an SMS-DELIVER PDU and return the hex (no SS7 send).
Report SM Delivery Status	POST /api/reportSM-DeliveryStatus	Report SM delivery outcome to the HLR.
Ready for SM	POST /api/readyForSM	Notify the HLR that an MS is reachable for SMS.
Alert Service Centre	POST /api/alertServiceCentre	Alert an SMSC that a subscriber is available.

Authentication

Operation	Endpoint	Description
Send Authentication Info	POST /api/send-auth-info	Retrieve authentication vectors from the HLR.
Send IMSI	POST /api/sendIMSI	Resolve an MSISDN to its IMSI at the HLR.

Subscriber Data

Operation	Endpoint	Description
Send Routing Info	POST /api/sri	Query the HLR for voice-call routing information.
Provide Subscriber Info	POST /api/provideSubscriberInfo	Request subscriber state/location from the VLR.
Delete Subscriber Data	POST /api/deleteSubscriberData	Remove subscriber data at the VLR (optional withdraw flags).
Any-Time Interrogation	POST /api/anyTimeInterrogation	gsmSCF queries subscriber info/location at the HLR.
Any-Time Subscription Interrogation	POST /api/anyTimeSubscriptionInterrogation	Query subscription data at the HLR.
Any-Time Modification	POST /api/anyTimeModification	Modify subscription data at the HLR.
Note Subscriber Data Modified	POST /api/noteSubscriberDataModified	HLR notifies the gsmSCF of changed data.
Note MM-Event	POST /api/noteMM-Event	Report a mobility-management event to the gsmSCF.

Supplementary Services

Operation	Endpoint	Description
Interrogate SS	POST /api/interrogateSS	Interrogate the status of a supplementary service.
Register SS	POST /api/registerSS	Register a supplementary service (e.g. call forwarding / CFU).
Erase SS	POST /api/eraseSS	Erase a supplementary service.
Activate SS	POST /api/activateSS	Activate a supplementary service.
Deactivate SS	POST /api/deactivateSS	Deactivate a supplementary service.
Register Password	POST /api/registerPassword	Register an SS password (ss_code integer).
Get Password	POST /api/getPassword	Retrieve/verify an SS password.
Forward Check SS Indication	POST /api/forwardCheckSS-Indication	Unconfirmed check toward a VLR (returns {"status":"sent"}).

The five core SS operations (interrogateSS, registerSS, eraseSS, activateSS, deactivateSS) share a request shape: ss_code (integer) and hlr_gt, with optional forwarded_to, no_reply_time, and basic_service.

Location Services (LCS)

Operation	Endpoint	Description
Send Routing Info for LCS	POST /api/sendRoutingInfoForLCS	GMLC queries the HLR for LCS routing.
Provide Subscriber Location	POST /api/provideSubscriberLocation	Request a subscriber's location from the serving node.
Subscriber Location Report	POST /api/subscriberLocationReport	Report a subscriber's location to the GMLC.

GPRS

Operation	Endpoint	Description
Update GPRS Location	POST /api/updateGprsLocation	Register a subscriber's serving SGSN with the HLR.
Send Routing Info for GPRS	POST /api/sendRoutingInfoForGprs	Query the HLR for GPRS routing (GGSN selection).

Equipment

Operation	Endpoint	Description
Check IMEI	POST /api/checkIMEI	Query equipment status at the EIR.

USSD

Operation	Endpoint	Description
USSD Send (network-originated)	POST /api/ussd/send	Push a USSD message to a subscriber. Requires ussd_gateway_enabled: true (else 503). See the USSD Gateway Guide.

CAP / CAMEL

Operation	Endpoint	Description
CAP InitialDP	POST /api/cap/initialDP	Trigger a CAMEL dialogue toward a gsmSCF. Returns an otid for follow-up ops.
CAP Connect	POST /api/cap/connect	Route the call to a destination (destination_number + otid).
CAP Continue	POST /api/cap/continue	Continue call processing (otid).
CAP Release Call	POST /api/cap/releaseCall	Release the call with a cause (otid).
CAP Apply Charging	POST /api/cap/applyCharging	Apply a charging window (duration + otid).

CAP follow-up operations carry the dialogue otid (hex, returned by initialDP) and respond with {"status":"sent","otid":"<hex>"}. See the CAMEL Gateway Guide.

Raw Injection (testing / diagnostics)

Operation	Endpoint	Description
Raw SCCP	POST /api/raw/sccp	Inject a hand-built SCCP payload (hex). Optional SCCP overrides (called/calling party, SSNs, OPC/DPC).
Raw M3UA	POST /api/raw/m3ua	Inject a hand-built M3UA payload (hex). Optional OPC/DPC/routing-context overrides.

Utility Endpoints

Endpoint	Method	Purpose
/metrics	GET	Prometheus metrics (text format).
/swagger	GET	Swagger UI.
/swagger.json	GET	OpenAPI specification.

---

Worked Examples

The following examples illustrate the request/response shape for representative operations. For the full field reference of every operation, see the MAP Client Guide.

SendRoutingInfo (SRI)

Retrieve routing information for establishing a call to a mobile subscriber.

Endpoint: POST /api/sri

Request Body:

{
  "msisdn": "1234567890",
  "gmsc": "5551234567"
}

Field	Type	Required	Description
msisdn	String	Yes	Called party MSISDN
gmsc	String	Yes	Gateway MSC Global Title

Response (200 OK):

{
  "result": {
    "imsi": "001001234567890",
    "msrn": "5551234999",
    "vlr_number": "5551234800"
  }
}

cURL Example:

curl -X POST http://localhost:8080/api/sri \
  -H "Content-Type: application/json" \
  -d '{"msisdn": "1234567890", "gmsc": "5551234567"}'

---

SendRoutingInfoForSM (SRI-for-SM)

Retrieve routing information for delivering an SMS to a mobile subscriber.

Endpoint: POST /api/sri-for-sm

Request Body:

{
  "msisdn": "1234567890",
  "service_center": "5551234567"
}

Field	Type	Required	Description
msisdn	String	Yes	Destination MSISDN
service_center	String	Yes	Service Center Global Title

cURL Example:

curl -X POST http://localhost:8080/api/sri-for-sm \
  -H "Content-Type: application/json" \
  -d '{"msisdn": "1234567890", "service_center": "5551234567"}'

---

UpdateLocation

Notify the HLR of a subscriber location change (VLR registration). In HLR mode this triggers the InsertSubscriberData (ISD) sequence.

Endpoint: POST /api/updateLocation

Request Body:

{
  "imsi": "001001234567890",
  "vlr": "5551234800"
}

Field	Type	Required	Description
imsi	String	Yes	Subscriber IMSI
vlr	String	Yes	VLR Global Title address

---

USSD Send (Network-Originated)

Push a USSD message to a subscriber. Requires ussd_gateway_enabled: true. For the full callback protocol and session lifecycle, see the USSD Gateway Guide.

Endpoint: POST /api/ussd/send

Request Body:

{
  "msisdn": "+254712345678",
  "text": "You have a pending bill. Reply 1 to pay.",
  "callback_url": "http://billing-app:9000/ussd"
}

Field	Type	Required	Description
msisdn	String	Yes	Destination subscriber MSISDN
text	String	Yes	USSD text to display (GSM 7-bit)
callback_url	String	Yes	URL to receive subscriber replies via HTTP POST

Response (200 OK):

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "sent"
}

Error (503 — gateway disabled):

{
  "error": "USSD gateway not enabled"
}

---

Authentication

Current Status: The API does not require authentication.

Security Considerations:

• API is intended for internal/trusted network use
• Consider using firewall rules to restrict access
• For production deployments, consider implementing authentication middleware

---

Response Formats

All responses use JSON format.

Success Response

HTTP Status: 200 OK

Structure:

{
  "result": {
    // Operation-specific response data
  }
}

Error Response

HTTP Status:

• 400 Bad Request - Invalid or missing request fields
• 500 Internal Server Error - Operation failed (non-timeout error returned by the SS7 stack)
• 503 Service Unavailable - Feature not enabled (USSD gateway)
• 504 Gateway Timeout - Operation timed out (default 10 seconds)
• 404 Not Found - Invalid endpoint

Structure:

{
  "error": "timeout"
}

or

{
  "error": "invalid request"
}

---

Error Handling

Common Errors

Error	HTTP Code	Description	Solution
Invalid JSON	400	Request body is not valid JSON	Check JSON syntax
Missing/invalid fields	400	Required fields missing or wrong type (responses often include a "required" list)	Include all required parameters with correct types
Operation error	500	SS7 stack returned a non-timeout error	Inspect the "error" message; check SS7 event logs
Feature disabled	503	USSD gateway not enabled	Set ussd_gateway_enabled: true
Timeout	504	Operation exceeded its timeout (default 10s)	Check M3UA connectivity, HLR/VLR availability
Not Found	404	Invalid endpoint	Check endpoint URL

Timeout Behavior

Awaited operations use a 10-second timeout by default:

1. Request sent to MapClient GenServer
2. Waits for response up to 10 seconds
3. If no response → returns 504 Gateway Timeout
4. If response received → returns 200 OK with result

Troubleshooting Timeouts:

• Check M3UA connection status (Web UI → M3UA page)
• Verify network element (HLR/VLR/MSC) is reachable
• Check routing configuration
• Review SS7 event logs for errors

---

Metrics (Prometheus)

The API exposes Prometheus metrics for monitoring.

Metrics Endpoint

URL: http://[server-ip]:8080/metrics

Format: Prometheus text format

Example Output:

# HELP map_requests_total Total MAP requests
# TYPE map_requests_total counter
map_requests_total{operation="sri"} 42
map_requests_total{operation="sri_for_sm"} 158
map_requests_total{operation="updateLocation"} 23

# HELP cap_requests_total Total CAP requests
# TYPE cap_requests_total counter
cap_requests_total{operation="initialDP"} 87
cap_requests_total{operation="requestReportBCSMEvent"} 91

# HELP map_request_duration_milliseconds Duration of MAP request/responses in ms
# TYPE map_request_duration_milliseconds histogram
map_request_duration_milliseconds_bucket{operation="sri",le="10"} 5
map_request_duration_milliseconds_bucket{operation="sri",le="50"} 12
map_request_duration_milliseconds_bucket{operation="sri",le="100"} 35
...

# HELP map_pending_requests Number of pending MAP TID waiters
# TYPE map_pending_requests gauge
map_pending_requests 3

# HELP omniss7_license_status Current license status (1 = valid, 0 = invalid)
# TYPE omniss7_license_status gauge
omniss7_license_status 1

Available Metrics

Metric	Type	Labels	Description
map_requests_total	Counter	operation	Total number of MAP requests by operation type
cap_requests_total	Counter	operation	Total number of CAP requests by operation type
map_request_duration_milliseconds	Histogram	operation	Request duration in milliseconds
map_pending_requests	Gauge	-	Number of pending MAP transactions
ussd_requests_total	Counter	direction	Total USSD requests (inbound/outbound)
ussd_active_sessions	Gauge	-	Number of active USSD sessions
omniss7_license_status	Gauge	-	Current license status (1 = valid, 0 = invalid)

Prometheus Configuration

Add to your prometheus.yml:

scrape_configs:
  - job_name: 'omniss7'
    static_configs:
      - targets: ['server-ip:8080']
    metrics_path: '/metrics'
    scrape_interval: 15s

---

Example Requests

Python Example

import requests
import json

# SRI-for-SM Request
url = "http://localhost:8080/api/sri-for-sm"
payload = {
    "msisdn": "1234567890",
    "service_center": "5551234567"
}

response = requests.post(url, json=payload, timeout=15)

if response.status_code == 200:
    result = response.json()
    print(f"Success: {result}")
elif response.status_code == 504:
    print("Timeout - no response from network")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript Example

const axios = require('axios');

async function sendSRI() {
  try {
    const response = await axios.post('http://localhost:8080/api/sri', {
      msisdn: '1234567890',
      gmsc: '5551234567'
    }, {
      timeout: 15000
    });

    console.log('Success:', response.data);
  } catch (error) {
    if (error.code === 'ECONNABORTED') {
      console.error('Timeout - no response from network');
    } else {
      console.error('Error:', error.response?.data || error.message);
    }
  }
}

sendSRI();

Bash/cURL Example

#!/bin/bash

# UpdateLocation Request
response=$(curl -s -w "\n%{http_code}" -X POST http://localhost:8080/api/updateLocation \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "001001234567890",
    "vlr": "5551234800"
  }')

http_code=$(echo "$response" | tail -n 1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -eq 200 ]; then
  echo "Success: $body"
elif [ "$http_code" -eq 504 ]; then
  echo "Timeout - no response from network"
else
  echo "Error $http_code: $body"
fi

---

Flow Diagrams

API Request Flow

---

Summary

The OmniSS7 REST API provides:

• 47 operation endpoints across Mobility, SMS, Authentication, Subscriber Data, Supplementary Services, Location Services, GPRS, Equipment, USSD, CAP/CAMEL, and Raw injection.
• Swagger UI at /swagger for interactive documentation and testing.
• Prometheus metrics at /metrics for monitoring and observability.
• 10-second default timeout for awaited operations (504 on timeout).
• A Plug.Cowboy HTTP server on port 8080, toggled by start_http_server — separate from the control panel (:8087) and :api_ex REST controllers (:8445).

For per-operation request/response schemas and MAP opcodes, see the MAP Client Guide.

For Web UI access, see the Web UI Guide.

For configuration details, see the Configuration Reference.