Note: in the examples shown throughout this page the URI path /api is used as a placeholder for the root URI path of the API. This might be for example:

https://sg-apim-rn.azure-api.net/globalnet-uat/api/v1/    (test environment)

https://sg-apim-rn.azure-api.net/globalnet/api/v1/        (production environment)

The API details show the full URI for each request.

Data Access Controls

The data available to each API user is controlled by their configured user account. When authenticating with the API, the client application supplies an API key (as described elsewhere), this key maps to a user in the Globalnet system. Each user is configured for access to one or more clients in the system and their associated equipment. By default, queries against the API methods will return data for the user's primary client. If data for another client is required, override the default client by supplying a client Id parameter in the query. For example:

// Get equipment for client Id 12345
GET /api/equipment?clientId=12345

// Get vouchers for client Id 12345
GET /api/products?clientId=12345&type=voucher

To list the clients accessible to the current login use:

GET /api/meta/user

Example response:

{
    "Email": "example@user.co.uk",
    "Clients": [
        {
            "Id": 999999,
            "Name": "Example Company XYZ",
            "IsDefault": true
        },
        {
            "Id": 8888888,
            "Name": "Example Company ABC",
            "IsDefault": false
        }
    ]
}

Equipment

List Equipment

List equipment items managed by the system.

GET /api/equipment

This request supports paging and filtering on client Id, client name (with partial matching) and equipment identifier (e.g. ICCID for a SIM). Some examples:

// Get the first 100 equipment items
GET /api/equipment?page=1&pageSize=100

// Get equipment on client 'ShipA'
GET /api/equipment?client=ShipA

// Get equipment with identifier '898789151616156'
GET /api/equipment?identifier=898789151616156

Example response:

{
    "ClientId": 12345,
    "ClientName": "Client XYZ",
    "Filter": {
        "IdentifierFilter": null,
        "ClientNameFilter": null,
        "CustomerReferenceFilter": null
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortOrder": "ClientName",
    "SortDirection": "Ascending",
    "TotalRows": 90,
    "Equipment": [
        {
            "Id": 556789,
            "ClientId": 456788,
            "ClientName": "Example Ship Z",
            "ClientPath": "[Company X] > [Company Y] > [Example Ship Z]",
            "EquipmentTypeId": 117,
            "EquipmentTypeName": "Iridium Certus",
            "IsPrepaid": false,
            "Identifier": "8988169771000088888",
            "Iccid": "8988169771000088888",
            "MsIsdnList": [ "881670000001","8816700000002" ],
            "Tags": null,
            "Status": "Activated",
            "IsDataSuspended": false,
            "StartDate": "2019-06-25T00:00:00Z",
            "EndDate": "2099-12-31T23:59:59.997Z",
            "OrderId": 0,
            "CustomerReference": null
        },
     ...]
}

Get Equipment Details

Details for an equipment item are retrieved using the equipment Id or ICCID of the item:

// get equipment item by unique Id
GET /api/equipment/{id}
e.g.
GET /api/equipment/12345

The equipment Id used in the query example above is that returned by the equipment listing method.

// get equipment item by ICCID
GET /api/equipment/{iccid}
e.g.
GET /api/equipment/898789151616156

Example response:

{
    "Id": 341277,
    "ClientId": 82640,
    "ClientName": "Example Ship Y",
    "CustomerRef": "On behalf of Example Ship Y (INV1111111)",
    "TopLevelClientId": 22222,
    "TopLevelClientName": "Top Leve Client",
    "Status": "Activated",
    "StartDate": "2015-01-13T00:00:00Z",
    "EndDate": "2099-12-31T23:59:59.997Z",
    "EquipmentTypeId": 1,
    "EquipmentTypeName": "Iridium SIM Card",
    "Identifier": "88163334445",
    "IccId": "898816932500111222",
    "Imei": "901033250123456",
    "Imsi": "901033250123456",
    "MasterMsisdn": "88163334445",
    "IsPrepaid": true,
    "AvailableActions": [
        "Suspend",
        "GetBalance",
        "RefreshBalance"
    ]
}

The AvailableActions property indicates the operations supported by the equipment item. Suspend indicates that the SIM may be suspended, GetBalance indicates a prepaid SIM where the balance is available for query, RefreshBalance indicates the balance value may be refreshed by a call to the operator service.

Get Vouchers for a Prepaid SIM

For prepaid SIMs the voucher products that can be applied to the equipment may queried by equipment id or equipment ICCID:

GET /api/equipment/{iccid}/vouchers

Example output:

{
    "ClientId": 1234567,
    "ClientName": "Example client",
    "Products": [
        {
            "Id": 164,
            "Name": "30 Day Extension",
            "Category": "Voucher",
            "ActivationType": null,
            "SimActivationUrl": null,
            "Announcement": "Valid on STD & Iridium Go! Plans",
            "Price": 99.99,
            "Deposit": 0.0,
            "Currency": "USD"
        },
    ...]

Get and/or Refresh Equipment Balance

For prepaid SIMs the equipment balance may queried by equipment id or equipment ICCID:

GET /api/equipment/{id}/balance
or
GET /api/equipment/{iccid}/balance

Example output:

{
    "EquipmentId": 55678,
    "Balance": 5960.00,
    "ExpiryDate": "2021-12-22T23:59:59.997Z",
    "LastBalanceCheckDate": "2021-07-16T00:11:01.96Z",
    "UnitsExpiring": null,
    "UnitsExpiryDate": null
}

To get the latest balance from the operator system use the refresh option. Note this option may take some seconds to return due to latency contacting the operator. For example:

GET /api/equipment/{id}/balance?refresh=true

Suspend and Resume SIM Equipment

If the SIM equipment supports the Suspend action the following command may be used:

PATCH /api/equipment/{id}

request body:

{
    "action": "suspend"
}

To resume (un-suspend) a SIM equipment item use the following:

PATCH /api/equipment/{id}

request body:

{
    "action": "resume"
}

SIM Equipment High Usage Alerts

The system allows the user to configure one or more monitors to check service usage for an equipment item. The monitor sends email alerts when usage reaches or exceeds the configured threshold. Usage that may be monitored includes: money, data volume, voice, and SMS text messages. Watch and alert settings for each SIM are accessed with the following call:

GET /api/equipment/{id}/watchalerts

Example response:

[
    {
        "DisplayName": "89111111112222",
        "Id": 999999,
        "EquipmentId": 123456,
        "AutoResume": false,
        "Threshold": 500.00,
        "AdditionalThreshold": 0.00,
        "CurrentBalance": 3.20,
        "StartDate": "2021-07-01T00:00:00Z",
        "DateDeleted": "0001-01-01T00:00:00",
        "ResetFrequency": 1,
        "RecipientAddresses": "user1@eaxmple.com, user2@example.com",
        "WatchTitle": "500.0 MB - Watch and Alert",
        "MeasurementUnit": "MB",
        "PercentageUsed": 0.0,
        "Status": "OK",
        "WatchAction": "Watch and Alert",
        "Reset": "Reset each month"
    }
]

SIM Top-up

To apply a voucher product to a prepaid SIM use the following:

POST /api/equipment/{id}/simtopups
or
POST /api/equipment/{iccid}/simtopups

request body:

{
    // product Id of the voucher product to apply to the SIM
    "productId": 31,
    "quantity": 1,
    "CustomerReference": "Your reference here"
}

The response body provides the new order Id for the SIM top-up:

{
    "OrderId": 00001
}

The product listing for prepaid vouchers is available using the following call; this gives the product Id to use for each prepaid voucher product.

GET /api/products?type=voucher

This returns the list of voucher products available.

Order History

To view your order history and the status of any recent orders use the following call:

GET /api/orders

This call takes an optional ClientId filter which defaults to the primary client associated with your account.

Example response:

{
    "ClientId": 11111,
    "ClientName": "Example Client",
    "Page": 1,
    "PageSize": 10,
    "Orders": [
        {
            "Id": 12345,
            "Date": "2021-11-23T10:21:58.91Z",
            "ClientId": 11111,
            "ClientName": "Example Client",
            "LoginId": 200000,
            "LoginName": "user@example.com",
            "CustomerReference": "",
            "Status": "Processing",
            "NetTotal": 0.0000,
            "SalesTax": 0.0000,
            "GrandTotal": 0.0000,
            "Currency": "USD",
            "InvoiceId": null
        },
	...]
}

Order details are available using the call:

GET /api/orders/{id}

This gives full order details with line items, checkout details, etc.

Invoice History

To view your invoice history use the following call:

GET /api/invoices?year=2021&month=8

This call takes an optional ClientId filter which defaults to the primary client associated with your account.

Example response:

{
    "ClientId": 11111,
    "ClientName": "Example Client",
    "Invoices": [
        {
            "Id": 9955588,
            "InvoiceDate": "2020-01-08T00:00:00Z",
            "DueDate": "2020-03-08T00:00:00Z",
            "InvoiceNumber": "FF01201111",
            "Amount": 60.0000,
            "Currency": "USD",
            "BillingCompany": "Example",
            "VesselName": null,
            "AccountNumber": "C000000"
        },
	...]
}

Invoice details are available using the call:

GET /api/invoices/{id}

You may download a PDF version of the invoice using the following call:

GET /api/invoices/{id}/pdf