API docs by Redocly

Monetization Hub API (3.0.1)

Download OpenAPI specification:

API Overview

With the IoT Monetization Hub API you can make your defined subscription plans directly available to your end customers via your webshop or app.

API Basics

The Hub's API is a straight forward REST API. This means, all end-points either create, retrieve, or update objects. API calls are authenticated with an API credential.

Main Concepts

Subscriptions are defined in the Hub based on following main parameters:

  • subscription tier: each subscription can be based on tiers, like base / medium / pro.
  • subscription limit: each subscription has defined limits per tier. The limits are number of devices and mobile data included.It is important to note, that the mobile data defined per tier are shared between the devices/SIM cards assigned to this subscription
  • bundle: a bundle is an add-on product to a subscription, that is usually added after the highest tier was purchased. A bundle can be an additional device, mobile data or both.

Authentication Controller

Controller to get an authentication token.

Log-In

Through this endpoint users can log-in to the API.
It is required to provide the fields username, password and backendUser. By default the backendUser shall be set to true

Request Body schema: application/json
required
username
string
password
string
backendUser
boolean

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "backendUser": true
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "issuedAt": 0,
  • "validTill": 0,
  • "access_token": "string"
}

User Controller

This controller has the purpose of engaging user related actions. Through this controller actions about the user creation and management are provided.

Returns user details by email

With this endpoint it is possible to get an user via a given email. The email is provided via a query parameter. Please be aware, that the email parameter is case sensitive.

Authorizations:
bearerAuth
query Parameters
email
required
string

email address of the user to be returned

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Response samples

Content type
application/json
{
  • "referenceId": "string",
  • "email": "string",
  • "firstName": "string",
  • "lastName": "string"
}

User registration

With this endpoint a new user will be created!

Authorizations:
bearerAuth
header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Request Body schema: application/json
required
firstName
string
lastName
string
email
string
birthDay
string
country
string
postalCode
string
city
string
street
string
streetNo
string
acceptTerms
boolean
acceptGDPR
boolean
language
string

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "birthDay": "string",
  • "country": "string",
  • "postalCode": "string",
  • "city": "string",
  • "street": "string",
  • "streetNo": "string",
  • "acceptTerms": true,
  • "acceptGDPR": true,
  • "language": "string"
}

Response samples

Content type
application/json
{
  • "userReferenceId": "string"
}

Simcard Controller

With this controller it is possible to manage SIM cards. Actions like assigning a SIM card to an user are provided.

Assigning a SIM card to an user

Through this endpoint a SIM card can be assigned to an user. It is required to have a proper registration code of the SIM card to assign it to the given user.
In the body of the request, the registration code needs to be entered as it uniquly identifies the respective SIM card.

Authorizations:
bearerAuth
header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Request Body schema: application/json
required
registrationCode
string

Responses

Request samples

Content type
application/json
{
  • "registrationCode": "XXXXX-XXXXX-XXXXX-XXXXX"
}

Response samples

Content type
application/json
{
  • "type": "SimCard",
  • "id": "123",
  • "attributes": {
    },
  • "relationships": {}
}

Subscription Controller

A controller for actions related to subscriptions. Through this endpoint the basic user oriented subscription management can be done.

Recieve available subscription tiers for upgrade

This endpoint gives information about the subscription tiers which are available for an upgrade of an existing user-subscription.
Please be aware, that an upgrade is only possible to a higher tier. If an user has already purchased the highest tier, no upgrade is possible and an empty list is returned.

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>

The id of the user-subscription for which upgrade options should be returned.

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upgrade a user-subscription

With this endpoint an user can upgrade to a higher subscription tier.
In the request body the id of the new tier should be provided.
If the upgrade was successful, a message indicating the success will be returned.

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>

The userSubscription id to identify which subscription from an user should be upgraded.

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Request Body schema: application/json
required

Model with the necessary information to perform a subscription upgrade.

tierId
integer <int64>

The id of the desired subscription tier.

Responses

Request samples

Content type
application/json
{
  • "tierId": 0
}

Response samples

Content type
application/json
{
  • "message": "subscription tier successfully upgraded"
}

Assign a bundle to an users subscription

Through this endpoint an user can assign a bundle to a desired subscription. A bundle is an add-on product to a defined subscription pla

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>
bundleId
required
integer <int64>
header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "clientId": 0,
  • "activeSince": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "subscriptionBundle": {
    },
  • "userSubscriptionId": 0
}

Assign SIM card to an users subscription

Via this endpoint a SIM card can be added to a subscription that is related to a specific user.
For every subscription a device limit is defined. There can be as many SIM cards added to a user-subscription as defined in the device limit.

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>

ID of the user-subscription to which the SIM card should be added.

simCardId
required
integer <int64>

ID of the SIM card which should be assigned.

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Remove SIM card from users subscription

With this endpoint, an assigned SIM card can be removed from a user-subscription.

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>

ID of the user-subscription from which the SIM card should be removed

simCardId
required
integer <int64>

ID of the SIM card which should be removed.

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Continue a paused userSubscription

With this endpoint a paused user-subscription can be continued.

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>

ID of the affected user-subscription

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Response samples

Content type
application/json
{
  • "message": "subscription successfully unpaused"
}

Assign/ Book a subscription for an user

With this endpoint a subscription can be assigned to a user. In the request body the Tier Id of the subscription to be assigned as well as the validity term shall be provided.
When the subscription was successfully assigned, the object userSubscription is returned. This object contains all relevant information of the user subscription.

Authorizations:
bearerAuth
header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Request Body schema: application/json
required

Necessary information for booking a subscription.

tierId
integer <int64>

The id of the subscription tier where the user should be assigned to.

validityId
integer <int64>

The id of the validity for the subscription tier to which the user should be assigned.

Responses

Request samples

Content type
application/json
{
  • "tierId": 0,
  • "validityId": 0
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "clientId": 1,
  • "active": true,
  • "lastAutoRenew": "2019-08-24T14:15:22Z",
  • "autoRenewReference": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "upgradeTierId": 0,
  • "upgradeValidityId": 0,
  • "validUntil": "2019-08-24T14:15:22Z",
  • "validityPercentage": 10,
  • "validityPeriod": 6,
  • "validityPrice": 12.5,
  • "currency": {
    }
}

Get subscriptions in specified views

With this endpoint you can retrieve all defined subscriptions. Based on the selected view you can define which subscriptions are requested.

Authorizations:
bearerAuth
query Parameters
view
required
string
Enum: "active" "available"

This request parameter is used for selecting a view. The values 'active' and 'available' are allowed, any other value will result in a bad request with the status code 400.

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get available bundles for user subscription

Over this endpoint the available bundles defined for an user-subscription are returned.
The returned bundles are those that can be purchased on top of a subscription. If there are no bundles configured or no bundles are available (this is depending on the tier level of the subscription) then an empty list is returned with the status code 200.
The ID of the users subscription (userSubscription ID) is provided over a path variable.

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>
header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Terminate/ Pause an user-subscription

With this endpoint an active user-subscription of an user can be paused or terminated.
Via the request parameter action the stop action for the user-subscription can be defined.
The action PAUSE does pause the subscription, that means the subscription can be used but will not be renewed anymore. It is always possible for the user to continue the subscription again with the /continue endpoint.
With TERMINATE the subscription is immediately stopped. The user then is not able to use the subscription anymore and all SIM balances are deactived immediately.

Authorizations:
bearerAuth
path Parameters
userSubscriptionId
required
integer <int64>

The ID of the affected userSubscription.

query Parameters
action
required
string
Enum: "PAUSE" "TERMINATE"

The action through which the subscription should be stopped for the user.

header Parameters
X-Impersonate-As
string

UUID of the user to be impersonated

Responses