Skip to main content

API Usage Examples

← Back to API Reference

Table of Contents​

Complete Subscriber Provisioning​

This example demonstrates the complete workflow for provisioning a new subscriber from scratch. The process involves creating all required profiles and components before creating the subscriber.

Prerequisites: This example uses jq for JSON parsing. Install with apt-get install jq or brew install jq.

Related Sections:

# 1. Create Key Set
KEY_SET_ID=$(curl -k -X POST https://hss.example.com:8443/api/key_set \
  -H "Content-Type: application/json" \
  -d '{
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "authentication_algorithm": "milenage",
    "amf": "8000",
    "sqn": 0
  }' | jq -r '.response.id')

# 2. Create APN QoS Profile
APN_QOS_ID=$(curl -k -X POST https://hss.example.com:8443/api/apn/qos_profile \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default Internet QoS",
    "allocation_retention_priority": 8,
    "apn_ambr_dl_kbps": 50000,
    "apn_ambr_ul_kbps": 25000,
    "pre_emption_capability": true,
    "pre_emption_vulnerability": true,
    "qci": 9
  }' | jq -r '.response.id')

# 3. Create APN Identifier
APN_ID=$(curl -k -X POST https://hss.example.com:8443/api/apn/identifier \
  -H "Content-Type: application/json" \
  -d '{
    "apn": "internet",
    "ip_version": "ipv4v6"
  }' | jq -r '.response.id')

# 4. Create APN Profile
APN_PROFILE_ID=$(curl -k -X POST https://hss.example.com:8443/api/apn/profile \
  -H "Content-Type: application/json" \
  -d "{
    \"apn_identifier_id\": \"$APN_ID\",
    \"apn_qos_profile_id\": \"$APN_QOS_ID\",
    \"name\": \"Internet APN\"
  }" | jq -r '.response.id')

# 5. Create EPC Profile
EPC_PROFILE_ID=$(curl -k -X POST https://hss.example.com:8443/api/epc/profile \
  -H "Content-Type: application/json" \
  -d "{
    \"apn_profiles\": [$APN_PROFILE_ID],
    \"name\": \"Standard Data Plan\",
    \"network_access_mode\": \"packet_only\",
    \"tracking_area_update_interval_seconds\": 600,
    \"ue_ambr_dl_kbps\": 100000,
    \"ue_ambr_ul_kbps\": 50000
  }" | jq -r '.response.id')

# 6. Create Subscriber
SUBSCRIBER_ID=$(curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"imsi\": \"001001123456789\",
    \"key_set_id\": \"$KEY_SET_ID\",
    \"epc_profile_id\": \"$EPC_PROFILE_ID\"
  }" | jq -r '.response.id')

echo "Subscriber provisioned successfully with ID: $SUBSCRIBER_ID"

What This Creates:

This provisioning workflow creates a complete subscriber with:

  1. Cryptographic keys (Key Set) - For authentication
  2. Data service profile (EPC Profile) - Bandwidth and network access settings
  3. APN configuration (APN Profile) - Access point with QoS
  4. Subscriber record (Subscriber) - The actual subscriber entity

Next Steps:

See Also:

Dormant Subscriber Pre-Provisioning​

Use this workflow to load subscribers in bulk from a SIM vendor output file, and to activate each subscriber later. This is the recommended model for most operators.

A dormant subscriber holds only its identity and its authentication keys. You add the phone number and the service profiles at activation. This matches the data that a SIM vendor sends you. The SIM vendor file contains the ICCID, the PIN, PUK, and ADM codes, and the authentication keys (Ki, OPc). The file does not contain a phone number or a service plan.

The database needs only the IMSI and the Key Set to insert a Subscriber. This is what makes a dormant record possible. It does not mean the other objects are optional for service. Each object is required for its own service: the EPC profile for data, the IMS profile and an MSISDN for voice, and a SIM for authentication. A dormant subscriber does not work on the network until you assign the matching object. You assign these objects when the customer activates the service. For the reason that the SIM, the Key Set, and the Subscriber are separate objects, see Key Set, SIM, and Subscriber.

Provisioning Lifecycle​

Step 1: Import (create the SIM, the Key Set, and a disabled Subscriber)​

Create one Key Set, one SIM, and one disabled Subscriber for each row in the SIM vendor file. This example uses jq to read the returned identifier from each response.

# 1. Create the Key Set from the SIM vendor file (Ki, OPc)
KEY_SET_ID=$(curl -k -X POST https://hss.example.com:8443/api/key_set \
  -H "Content-Type: application/json" \
  -d '{
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "authentication_algorithm": "milenage",
    "amf": "8000",
    "sqn": 0
  }' | jq -r '.response.id')

# 2. Create the SIM from the SIM vendor file (ICCID, PIN/PUK/ADM)
SIM_ID=$(curl -k -X POST https://hss.example.com:8443/api/sim \
  -H "Content-Type: application/json" \
  -d '{
    "iccid": "8944000000000000001",
    "is_esim": false,
    "ind_length": 5
  }' | jq -r '.response.id')

# 3. Create the Subscriber in a disabled state.
#    imsi and key_set_id are required. Link the SIM. Add no MSISDN and no profiles.
SUBSCRIBER_ID=$(curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"imsi\": \"001010000000001\",
    \"key_set_id\": \"$KEY_SET_ID\",
    \"sim_id\": \"$SIM_ID\",
    \"enabled\": false,
    \"ims_enabled\": false
  }" | jq -r '.response.id')

A dormant Subscriber is safe to keep in the database. The subscriber does not attach, authenticate, or register while it is disabled. If the network queries a dormant subscriber, the HSS rejects the request. See Dormant Subscriber Behaviour on the Network.

Step 2: Activate (assign the number and the profiles, then enable)​

To activate a subscriber, send one PATCH request. Add the MSISDN, assign the profiles, and set enabled to true.

curl -k -X PATCH https://hss.example.com:8443/api/subscriber/$SUBSCRIBER_ID \
  -H "Content-Type: application/json" \
  -d "{
    \"enabled\": true,
    \"ims_enabled\": true,
    \"msisdns\": [\"$MSISDN_ID\"],
    \"epc_profile_id\": \"$EPC_PROFILE_ID\",
    \"ims_profile_id\": \"$IMS_PROFILE_ID\",
    \"roaming_profile_id\": \"$ROAMING_PROFILE_ID\"
  }"

A PATCH request changes only the fields that you send. The IMSI, the Key Set, and the SIM stay as they are. Create the MSISDN and the profiles first, or reuse existing identifiers. See Complete Subscriber Provisioning for how to create the profiles.

Step 3: Deactivate (disable the subscriber)​

To deactivate a subscriber, set enabled to false. The subscriber record and its data stay in the database.

curl -k -X PATCH https://hss.example.com:8443/api/subscriber/$SUBSCRIBER_ID \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "ims_enabled": false
  }'

To remove IMS voice only, and to keep the data service, set ims_enabled to false and leave enabled as true.

Dormant Subscriber Behaviour on the Network​

A subscriber fails closed while it is dormant or disabled. The HSS rejects the request on the network interface. The HSS also writes a warning log with the exact reason. The reason is one of the following:

  • The subscriber is disabled (enabled is false).
  • IMS is disabled for the subscriber (ims_enabled is false).
  • A required object is not assigned yet. For example, there is no EPC profile for an LTE attach, or no IMS profile for IMS registration.

The reject uses the Experimental-Result-Code DIAMETER_ERROR_USER_UNKNOWN (5001) on the S6a and Cx interfaces, per 3GPP TS 29.272 and 3GPP TS 29.229. The warning log names the IMSI and the exact reason. The log lets you tell a dormant subscriber apart from an unknown IMSI.

Complete Static IP Provisioning​

This example demonstrates provisioning a subscriber with a static IP address from scratch.

Scenario: Provision an IoT device subscriber that needs a static IPv4 address on the "internet" APN.

# Prerequisites: jq must be installed (apt-get install jq or brew install jq)

# 1. Create Key Set
KEY_SET_ID=$(curl -k -X POST https://hss.example.com:8443/api/key_set \
  -H "Content-Type: application/json" \
  -d '{
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "authentication_algorithm": "milenage",
    "amf": "8000",
    "sqn": 0
  }' | jq -r '.response.id')

# 2. Create APN QoS Profile
APN_QOS_ID=$(curl -k -X POST https://hss.example.com:8443/api/apn/qos_profile \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IoT Best Effort",
    "allocation_retention_priority": 8,
    "apn_ambr_dl_kbps": 10000,
    "apn_ambr_ul_kbps": 5000,
    "pre_emption_capability": false,
    "pre_emption_vulnerability": false,
    "qci": 9
  }' | jq -r '.response.id')

# 3. Create APN Identifier
APN_ID=$(curl -k -X POST https://hss.example.com:8443/api/apn/identifier \
  -H "Content-Type: application/json" \
  -d '{
    "apn": "internet",
    "ip_version": "ipv4"
  }' | jq -r '.response.id')

# 4. Create APN Profile
APN_PROFILE_ID=$(curl -k -X POST https://hss.example.com:8443/api/apn/profile \
  -H "Content-Type: application/json" \
  -d "{
    \"apn_identifier_id\": \"$APN_ID\",
    \"apn_qos_profile_id\": \"$APN_QOS_ID\",
    \"name\": \"IoT Internet APN\"
  }" | jq -r '.response.id')

# 5. Create Static IP for the APN
STATIC_IP_ID=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d "{
    \"apn_profile_id\": \"$APN_PROFILE_ID\",
    \"ipv4_static_ip\": \"100.64.1.100\"
  }" | jq -r '.response.id')

# 6. Create EPC Profile
EPC_PROFILE_ID=$(curl -k -X POST https://hss.example.com:8443/api/epc/profile \
  -H "Content-Type: application/json" \
  -d "{
    \"apn_profiles\": [$APN_PROFILE_ID],
    \"name\": \"IoT Data Plan\",
    \"network_access_mode\": \"packet_only\",
    \"tracking_area_update_interval_seconds\": 600,
    \"ue_ambr_dl_kbps\": 10000,
    \"ue_ambr_ul_kbps\": 5000
  }" | jq -r '.response.id')

# 7. Create MSISDN (phone number)
MSISDN_ID=$(curl -k -X POST https://hss.example.com:8443/api/msisdn \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "14155551000"
  }' | jq -r '.response.id')

# 8. Create Subscriber with Static IP
SUBSCRIBER_ID=$(curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"imsi\": \"001001999999999\",
    \"key_set_id\": \"$KEY_SET_ID\",
    \"epc_profile_id\": \"$EPC_PROFILE_ID\",
    \"msisdns\": [$MSISDN_ID],
    \"static_ips\": [$STATIC_IP_ID]
  }" | jq -r '.response.id')

echo "IoT Subscriber provisioned successfully!"
echo "  Subscriber ID: $SUBSCRIBER_ID"
echo "  IMSI: 001001999999999"
echo "  MSISDN: 14155551000"
echo "  Static IPv4: 100.64.1.100 (on 'internet' APN)"

What This Creates:

This provisioning workflow creates a complete IoT subscriber with:

  1. Cryptographic keys (Key Set) - For authentication
  2. APN configuration (APN Profile) - "internet" access point
  3. Static IP assignment (Static IP) - Fixed IPv4 address 100.64.1.100
  4. Data service profile (EPC Profile) - IoT-optimized bandwidth limits
  5. Phone number (MSISDN) - For device identification
  6. Subscriber record (Subscriber) - The complete subscriber entity

Result:

When this subscriber attaches to the network and connects to the "internet" APN, they will receive the static IP address 100.64.1.100 instead of a dynamic DHCP address.

Next Steps:

  • Add additional APNs with static IPs: Repeat steps 2-5 for each APN
  • Enable voice services: Create and assign IMS Profile
  • Configure roaming: Create and assign Roaming Profile
  • Link physical SIM: Create and assign SIM

See Also:

← Back to API Reference

Last updated on