Globalnet SIM Activation - Worked Example

This page shows an example of all the calls required to activate a SIM using the Globalnet API. Go back to the Globalnet Developer Guide.

Prerequisites

In this example we will activate an Inmarsat BGAN SIM. We must have our API key and know the SIM number (ICCID) of the SIM we wish to activate. This SIM must be loaded onto the Globalnet database.

Get the Product Details

Option 1: use the product listing to view the activation products available to your account:

GET /api/v1/products?type=activation&clientId={my-clientId}

The client Id parameter is optional. It is only required if you have more than one billing client assigned to your user account. If it is not specified it will default to your Primary Client.

Validate the ICCID: When you have selected a product to activate the SIM under, ensure the SIM is valid for the product:

POST /api/v1/activations/validateiccid

{
    "ClientId": 12345,
    "ProductId": 1,
    "Iccid": "898709906412250011"
}

This will return HTTP 200 OK if the SIM is suitable, or HTTP 400 Bad Request if the SIM cannot be used for the activation, for example:

{ "Messages": [ "Iccid: SIM has already been used." ] }

Option 2: list all products that are valid for our example SIM number: 898709906412250011. We can list all the activations for our SIM using this call:

GET /api/v1/products/iccid/898709906412250011?clientId={my-clientId}

Response:

{
    "ClientId": 12345,
    "ClientName": "Example client",
    "Products": [
        {
            "Id": 1,
            "Name": "BGAN Postpaid Standard Plan",
            "Category": "Activation",
            "ActivationType": "InmarsatBganPostpaid",
            "SimActivationUrl": "api/v1/activations/inmarsat/bgan",
            "Announcement": null,
            "Price": 0.0,
            "Deposit": 0.0,
            "Currency": "USD"
        }, 
...]

In this case we will use product 1 "BGAN Postpaid Standard Plan".

Note the product activation URL

The SimActivationUrl in the product details tells us the URL we need to use for the activation request. In this example:

POST /api/v1/activations/inmarsat/bgan

Get the Product Options

The Inmarsat BGAN activation request body is of type: InmarsatBganActivationRequest (see the API documentation for further details).

Before we can make the activation request we need to get the various options for this product:

GET /api/v1/products/1/options

{
    "ProductId": 1,
    "ProductName": "BGAN Postpaid Standard Plan",
    "ClientId": 12345,
    "ClientName": "Example Client",
    "ActivationType": "InmarsatBganPostpaid",
    "StandardFeatures": [
        "Telephony",
        "Sms",
        "StandardIp"
    ],    
    "OptionalFeatures": [
        "Voicemail",
        "Fax",
        "Isdn",
        "Streaming"
    ]
}

In this case we can see the Features property of our activation request body must have Telephony, Sms, and StandardIp values set to true. Voicemail, Fax, Isdn, and Streaming may all be set to true or false.

Get the Firewall application options

The API documentation shows that the InmarsatBganActivationRequest requires the Firewall property to be set. To get the valid values for the AllowedApplications property of the ActivationFirewall we call:

GET /api/v1/products/{product-id}/options/firewallapplications

Typical response:

[    "Amos",    "Dualog",    "IPSignature 3", ...]

Get the Data Streaming options

The API documentation shows that the InmarsatBganActivationRequest has an optional the DataStreaming property. If you require data streaming, to get the valid values we call:

GET /api/v1/products/{product-id}/options/datastreamingoptions?clientId={client-id}

Note that the client id filter is optional. Defaults to the user's primary billing client. Typical response:

[
    {
        "Name": "None",
        "Value": "None"
    },
    {
        "Name": "Streaming 128kbps",
        "Value": "Streaming 128kbps;SYMM128"
    },
    {
        "Name": "Streaming 176kbps",
        "Value": "Streaming 176kbps;SYMM176"
    },
...]

We would set the DataStreaming property of the SIM activation request body to one of the Value properties listed above, e.g.: "Streaming 176kbps;SYMM176"

Get Industry Code options

The API documentation shows that the InmarsatBganActivationRequest requires the IndustryCode property to be set. To get the valid values for this property we call:

GET /api/v1/products/{product-id}/options/industrycodes?clientId={client-id}

Note that the client id filter is optional. Defaults to the user's primary billing client. Typical response:

[    "Agriculture",    "Aid & NGO",    "Banking",    "Construction", ...]

Get the Service Plan options

The API documentation shows that the InmarsatBganActivationRequest supports the ServicePlan property. To get the valid values for this property we call:

GET /api/v1/products/{product-id}/options/serviceplans?clientId={client-id}

Note that the client id filter is optional. Defaults to the user's primary billing client. Typical response:

[
    {
        "Name": "Monthly",
        "Value": "Monthly"
    },
    {
        "Name": "Quaterly",
        "Value": "Quaterly;QT"
    }
]

Validate the IMEI

If you include an IMEI for the BGAN terminal in the activation request body, it is a good idea to validate that the IMEI is OK to use with the product:

POST /api/v1/activations/validateiccid

{
    "ClientId": 12345,
    "ProductId": 1,
    "Imei": "012345678901234"
}

This will return HTTP 200 OK if the IMEI is valid, or HTTP 400 Bad Request if the IMEI cannot be used for the activation:

{ "Messages": [ "Imei is valid" ] }

Get the list of Countries for the Contact Details

The API documentation shows that the InmarsatBganActivationRequest requires the ContactDetails property to be set. To get the valid values for the CountryId property of the CustomerContactDetail we call:

GET /api/v1/countries

Typical response:

[
    { "Id": 1, "Iso3Code": "AFG", "Name": "Afghanistan" },
    { "Id": 2, "Iso3Code": "ALB", "Name": "Albania"     },
...]

Send the SIM activation request

Build the request body based on values retrieved from the valid options and send the SIM activation request:

POST /api/activations/inmarsat/bgan

{
    "Header": {
        "ClientId": 12345,
        "ProductId": 1,
        "CustomerReference": "My customer reference",
        "FutureActivationDate": null
    },
    "Iccid": "898709906412250011",
    "ContactDetail":{
        "Attention": null,
        "StreetAddress": "",
        "Postcode":"",
        "City":"",
        "County":"",
        "CountryId": 1,
        "Email": "sg.postman.test@mailinator.com",
        "Telephone": "0123 4567 8910"
    },
    "Features" : {
        "Telephony" : true,
        "Sms" : true,
        "Voicemail" : true,
        "StandardIp" : true,
        "LowSpeedData" : true,
        "Fax" : false,
        "Isdn" : false
    },
    "DataStreaming": null,
    "Terminal": {
        "Imei": null,
        "Manufacturer": "Cobham",
        "Model": "BGAN 500",
        "SerialNumber": "12300000111"
    },
    "Firewall": {
        "OpenWebAccess": false,
        "RequestInfrastructureSupport": false,
        "AllowedApplications": [
            "IPSignature 3",
            "IPSignature 4",
            "Web Access - http/https/dns only (at your own risk)"
        ],
        "Requirements":[
            {
                "Description": "ESET Updates",
                "Ports": "4444,4445",
                "IpAddresses": "192.168.0.1,192.168.0.2"
            }
        ]
    },
    "WatchAlerts": [
        {
            "WatchType" : "MoneyUsd",
            "ActionType" : "Alert",
            "Threshold" : 150.00,
            "Recipients" : ["recip1@testemail.com", "recip2@testemail.com"]
        },
        {
            "WatchType" : "DataMb",
            "ActionType" : "Suspend",
            "Threshold" : 1000.0,
            "Recipients" : ["recip1@testemail.com", "recip2@testemail.com"]
        }
    ],
    "ServicePlan": "Monthly",
    "IndustryCode": "Travel and Tourism"
}