API Documentation
Getting Started
Event Documentation
FAQ
Service Information

The M2M Service Portal 3.0 REST API

The REST API is secured using Oauth2 and 'OpenID Connect'. Customer acknowledges that the execution of certain functionalities using the REST API may cause further costs according to the agreements of the M2M framework agreement.

Architecture and overall processing

The new REST API is deployed via a dedicated API Gateway providing the external interface. Incoming calls are processed by the Gateway with corresponding customer requests first being authenticated using an integrated IAM solution. The customer request is then forwarded to the REST API together with a valid token. The token is once again validated by the M2M Service Portal 3.0 thereby authenticating and authorizing valid customer requests. The desired operation is executed on the M2M Service Portal 3.0 platform and in the backend systems. Results are returned to the customer as part of the synchronous communication.

Authentication Mechanism

As mentioned in the beginning of this chapter and shown in above and below figures, the communication is secured using the standard 'OpenID Connect' protocol and tokens.

If you have booked the service REST API, the following applies: As soon as contract administration has processed your order the user for the technical contact will find a self administration area in the M2M Service Portal. Please check in My Partner Data the tab REST API. In this section you can either register new applications for REST API communication or manage existing ones incl. its individual client id and client secret.

Technical Parameters

You can access the productional REST API with the following URL:

The external base url: 'https://sg-api.telekom.de'
The M2M Service Portal 3.0 specific base path: '/iot/connectivity/management/v1'

A corresponding GET Request could look as follows:

https://sg-api.telekom.de/iot/connectivity/management/v1/partners/[partnerId]/sims

Partner IDs

The attribute [partnerID] used in the URL must always reference the partner ID the SIM cards belong to. This can either be the partner ID of a Superunit or a Subunit.

  • In case the SIM cards belong directly to the Superunit, the partner ID of the Superunit must be used. The partner ID of the Superunit can be found in your Customer Portal (GUI) under "My Partner Data".
  • In case the SIM cards belong to a Subunit, the partner ID of the corresponding Subunit must be used. The partner ID of the Subunit can be found in your Customer Portal (GUI) under "My Subunits".

 

SIM Card Identifiers

Via POST requests, SIM cards can be selected by different identifiers like ICCID, eUICCID (eID), IMSI, IMEI (IMEISV) or MSISDN. Some identifiers may not be available depending on the request or type and status of the SIM card(s) (e.g. physical or virtual SIM card, productive or not productive). IMEI and IMEISV can equally be used to identify a SIM card.

For requests with the identifier in the resource path only ICCID is allowed.

See the following table for possible identifiers:

Possible SIM Card Identifiers

Method
ICCID
eUICCID
IMSI
IMEI
MSISDN
SIM Quantity
[GET] Get SIM List †
[GET] Get SIM Details *
single
[POST] Get SIM Details **
(✔)
(✔)
(✔)
single
[GET] Get SIM Session *
single
[POST] Get SIM Session **
(✔)
single
[GET] Get SIM Session History *
single
[POST] Get SIM Session History **
(✔)
single
[GET] Get SMS History *
single
[POST] Get SMS History **
(✔)
single
[POST] SIM Activation
(✔)
(✔)
bulk
[POST] SIM Block
(✔)
bulk
[POST] Bind eUICCID
(✔)
bulk
[POST] Reset Fraud Status
(✔)
bulk
[POST] Override Limit Status
(✔)
bulk
[POST] Reset Limit Status
(✔)
bulk
[POST] Restore Limit Status
(✔)
bulk
[POST] Enter Productive State
(✔)
bulk
[POST] SIM Modify Profiles
(✔)
bulk
[POST] SIM Modify Remarks
(✔)
(✔)
(✔)
bulk
[POST] SIM Restrict
(✔)
bulk
[POST] SIM Move
(✔)
(✔)
(✔)
bulk
[POST] SIM Suspend
(✔)
bulk
[POST] SIM Change Tariff
(✔)
bulk
[POST] SIM Change Option
(✔)
single
[POST] SIM Book Option
(✔)
bulk
[POST] SIM Terminate Option
(✔)
bulk
[POST] SIM Termination
(✔)
bulk
[POST] SIM Unblock
(✔)
bulk
[POST] SIM Unrestrict
(✔)
bulk/single
[POST] SIM Unsuspend
(✔)
bulk
[POST] Check SIM in HLR *
single
[POST] Check SIM in HLR **
(✔)
single
[POST] Reset SIM in HLR *
single
[POST] Reset SIM in HLR **
(✔)
single
[POST] Send Message *
single
[POST] Send Message **
(✔)
single
[POST] Create SIM Transfer
(✔)
(✔)
(✔)
bulk

† Identifier as search parameter
* ICCID only support
** Multiple identifier support

 

Server Sent Events

For asynchronous actions on TMSP, server sent events (SSE) are used. These methods rely on GET calls that follow the OAuth2 client credential flow. Therefore, the onboarding is easy and there is no need for customers to expose reachable endpoints.

The retrieval of events works with GET requests using dedicated ressources per event type. You find the specific event URLs for your API subscriptions in the REST API page of the M2M Service Portal 3.0. The payload of the events itself can be found under Event Definition.

Detailed Implementation Guideline

  1. Your application has to send a GET request to the SSE endpoint described in the M2M Service Portal 3.0 including a Bearer Token.
  2. The gateway will respond once with an HTTP 200 and keep the connection open. The events will be sent via this open connection.
  3. The gateway will respond by default with the MIME type application-stream/json. This follows the Spring Webflux implementation. Other frameworks expect the MIME type text/event-stream according to the W3C Standard. The gateway caters for this standard, when the corresponding Accept header is set in the request. Please check, if your framework requires you to specifically enable this header.
    Content-Type: text/event-stream;charset=UTF-8
    Accept:       text/event-stream
    Example header settings.
  4. The open connection will automatically be closed after 60 seconds. You will see an HTTP 504, which is not an error. Your application has to open another connection to receive further events.
  5. If you open a new SSE connection and there exists already an open one, the latter one will be closed to prevent accidental double sending of events.

Please Note:

To gain access to the SSE, you might create a new REST application access in the partner portal. As soon as you change out the according client data, you are able to retrieve events.

 

Protective Measures

The M2M Service Portal 3.0 REST API can be used by customers been subscribed to the REST API service to administrate and monitor related IoT SIMs. To ensure all users a superior platform experience certain rate limits are defined. The rate limits below are available per customer and may be handled dynamically on a higher level if platform capacity is available. In case capacity limits are exceeded the platform will return a response.

Methods
Resource Path
Limit
[POST] SIM Actions (standard methods w/o SIM Transfer)
/sims/actions/*
up to 10k SIMs/h
(max. of 1k SIMs/6 mins)
[GET] SIM Details
/sims/{iccid}
up to 10k SIMs/h
(max. of 1k SIMs/6 mins)
[GET] Session History, Session Details, SMS History
/sims/{iccid}/*
up to 2.5k SIMs/h
(max. of 250 SIMs/6 mins)
[POST] SMS Send Message
/sims/{iccid}/sms
Only for diagnostic purposes of single SIMs.

{
  "status": "FORBIDDEN",
  "message": "Limit exceeded",
  "errors": [
    "Too Many Concurrent Requests on Platform."
  ],
  "timestamp": "2025-08-28 11:25:49"
}
Error message for exceeded request limit (error code 403).

Please Note:

The authentication mechanism used by the REST API is based on OAuth and OpenID. As shown below, the customer uses the client id and client secret in order to generate a token which is then sent to the Deutsche Telekom Gateway as part of the request. The token is validated by the backend and used in order to authenticate the user and authorize the requested operation.

In order to successfully generate a client token and authenticate to the Deutsche Telekom Gateway, the following parameters need to be configured within the new request:

Parameter
Value
Type
OAuth 2.0
Add authorization data to
Request Headers
Token Name
Custom label (e.g. Pilot Token)
Access Token URL / Token Issuer URL
https://sg-api.telekom.de/auth/realms/default/protocol/openid-connect/token
Client ID
Individual parameter. Client ID is found in the M2M Service Portal.
Client Secret
Individual parameter. Client Secret is found in the M2M Service Portal.
Scope
openid profile
Client Authentication
Send client credentials in body
Grant Type
Client credentials

 

Application Management in the Portal

REST API

Via the tab "REST API" you can call up an overview in which all registered applications are displayed.

Figure 1: REST API overview


The table displays all created accounts. All users with their Client ID, Status, IRIS Client ID, IRIS Client Secret, etc. are visible on the first level. By clicking on the plus symbol, various event types with the corresponding subscription URL are displayed. If no URLs are available for this user, no plus symbol is displayed.
By clicking on Show IRIS Client Secrets, you can easily show the values for all users.

Figure 2: Corresponding subscription URLs


Register new application

Figure 3: Register new application


Via the function "Register new application" you can call up the mask for entering the user name.
Clicking on "Save" opens a window.

Figure 4: Register new application details


A) Read Only

If the read-only slider is activated, the user is granted read-only rights. Changes to the data are not possible in this mode.

B) IP-Whitelist

By clicking on the plus symbol, up to ten IPv4 addresses can be added to the whitelist.
To remove an IP address, click on the trash can icon next to the corresponding address.

C) Subunit user

To create a subunit user, select the corresponding option under User type.
In the subsequent dialog, you can assign the desired subunits to the user.


Figure 5: Confirm account registration


Click on "Save" again to complete the creation process.
Afterwards you will find a new entry in the overview (visible in figure 1), which informs you about the current status of the creation.

Delete application

Figure 6: Delete application


If you want to delete an account, click on the trash can. A popup window will appear where you can confirm the deletion of the account.

 

Server Sent Events

As mentioned in section Getting Started there are different payloads possible regarding the event type.


SIM Action

A SIM Action event is provided when an action is started via a POST call in the Customer REST API and the corresponding workflow is finished.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000706409461",
  "source": "/v1/partners/simaction",
  "specversion": "1.0",
  "type": "simaction.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "100013",
    "signupID": "708855306",
    "message": "Action with signup ID 708855306 is done.",
    "actionLink": {
      "rel" : "actions",
      "href": "http://172.19.14.203:8083/v1/partners/100013/sims/actions/708855306",
      "type": "GET",
      "name": "get action status"
    }
  }
}
Example event of a successful SIM card activation.

Parameter
Data Type
Description
actionLink
object
HATEOAS information for the corresponding action
data
object
Specific payload of the event
datacontenttype
string
MIME type of the response
id
string
Event ID
message
string
Specific message for the event
partnerID
string
Partner ID of the customer
signupID
number
Signup ID of the SIM action
source
string
Source of the event
specversion
string
Current specifications version
time
string
UTC timestamp of the event
type
string
Event type

SIM Transfer Notifications (* optional service)

SIM Transfer Notifications are special SIM Action events which additionally contain the transaction ID and are sent not only when the corresponding workflow is finished, but also in various other places of the SIM Transfer workflow.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000706409461",
  "source": "/v1/partners/simaction",
  "specversion": "1.0",
  "type": "simaction.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "100013",
    "transactionID": "1002946614",
    "signupID": "708855337",
    "action" : "REQUESTED",
    "message": "You have received a request from 'Telekom Main Test Company' to add SIM cards to your inventory. Please follow the link to accept or reject them.",
    "actionLinks": {
      "accept": {
        "rel": "accept",
        "href": "https://mmint4.dev-vie.int.compax.at/m2m-customerapi-restservice/v1/partners/100015/sims/actions/simtransfer/1002947462",
        "type": "PATCH",
        "name": "update SIM transfer"
      },
      "reject": {
        "rel": "reject",
        "href": "https://mmint4.dev-vie.int.compax.at/m2m-customerapi-restservice/v1/partners/100015/sims/actions/simtransfer/1002947462",
        "type": "PATCH",
        "name": "update SIM transfer"
      },
      "sims": {
        "rel": "sims",
        "href": "https://mmint4.dev-vie.int.compax.at/m2m-customerapi-restservice/v1/partners/100015/sims/actions/simtransfer/1002947462",
        "type": "GET",
        "name": "get SIM transfer details"
      }
    }
  }
}
Event sent out for the receiving partner, informing about the pending SIM Transfer.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000706409461",
  "source": "/v1/partners/simaction",
  "specversion": "1.0",
  "type": "simaction.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "100017",
    "transactionID": "1002946615",
    "signupID": "708855337",
    "action" : "REJECTED",
    "message": "'Telekom Secondary Test Company' has rejected your SIM Transfer request.",
  }
}
Event sent out for the sending partner, informing about the rejection of the SIM Transfer by the receiving partner.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000706409461",
  "source": "/v1/partners/simaction",
  "specversion": "1.0",
  "type": "simaction.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "100013",
    "transactionID": "1002946615",
    "signupID": "708855337",
    "action" : "CANCELLED",
    "message": "'Telekom Main Test Company' has cancelled the request to transfer SIM cards.",
  }
}
Event sent out for the receiving partner, informing about the cancellation of the SIM Transfer by the sending partner. Additionally, this event is sent out for both receiving and sending partner in case the SIM Transfer is cancelled by the operator.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000706409461",
  "source": "/v1/partners/simaction",
  "specversion": "1.0",
  "type": "simaction.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "100017",
    "transactionID": "1002946615",
    "signupID": "708855337",
    "action" : "COMPLETED",
    "message": "'The SIM Transfer between 'Telekom Main Test Company' and 'Telekom Secondary Test Company' has been completed.",
  }
}
Event sent out for both the receiving and the sending partner, informing about the completion of the SIM Transfer.

Parameter
Data Type
Description
actionLink
object
HATEOAS information for the corresponding action
data
object
Specific payload of the event
datacontenttype
string
MIME type of the response
id
string
Event ID
message
string
Specific message for the event
partnerID
string
Partner ID of the customer
signupID
number
Signup ID of the SIM action
transactionID
number
ID of the SIM Transfer transaction
source
string
Source of the event
specversion
string
Current specifications version
time
string
UTC timestamp of the event
type
string
Event type

Profile Notification

A Profile Notification is provided for a SIM card when a condition of an assigned limit profile or fraud profile is triggered. This can be a detected violation of a session or usage limit – or a device or location fraud.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000706406251",
  "source": "/notification/limit",
  "specversion": "1.0",
  "type": "profilenotification.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "100013",
    "sim": {
      "iccid": "8999829698800485278",
      "restrictionStatus:": "Speed Step-down"
    },
    "profileStatus": {
      "barring": "Session Limit",
      "barringType": "Limit",
      "barringLevel": 2,
      "allowed": "5",
      "detected": "6",
      "note": "Reached: Limit 2 Allowed (sessions): 5 Detected (sessions): 6"
    }
  }
}
Example event of a session limit violation of a zone specific limit profile.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000706406251",
  "source": "/notification/limit",
  "specversion": "1.0",
  "type": "profilenotification.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "100013",
    "sim": {
      "iccid": "8999829698800485278",
      "restrictionStatus:": "Speed Step-down"
    },
    "profileStatus": {
      "barring": "Session Limit",
      "barringType": "Limit",
      "barringLevel": 2,
      "allowed": "5",
      "detected": "6",
      "note": "Reached: Limit 2 Allowed (sessions): 5 Detected (sessions): 6",
      "apn": {
        "apnName": "b2b.dtag.test",
        "restrictionStatus": "Speed Step-down"
      }
    }
  }
}
Example event of a session limit violation of an APN specific limit profile.

Parameter
Data Type
Description
allowed
string
Allowed value corresponding to the type of barring
apn
object
Information about the APN which triggered the notification
apnName
string
Name of the APN which triggered the notification
barring
string
Reason of barring ("Session Limit", "Usage Limit", "Device Fraud", "Location Fraud")
barringLevel
number
Level of barring (1 = warning, 2 = alarm)
barringType
string
General type of barring ("Limit" or "Fraud")
data
object
Specific payload of the event
datacontenttype
string
MIME type of the response
detected
string
Detected value corresponding to the type of barring
iccid
string
ICCID of the affected SIM card
id
string
Event ID
note
string
Combined description of the profile status
partnerID
string
Partner ID of the customer
profileStatus
object
Information about the corresponding profile status
restrictionStatus
string
Restriction status of the SIM card / APN ("No Restriction", "Speed Step-down", "Data Restricted")
sim
object
Information about the affected SIM card
source
string
Source of the event
specversion
string
Current specifications version
time
string
UTC timestamp of the event
type
string
Event type

Pool Limit Notification

A Pool Limit Notification is provided when a limit level of an assigned pool limit profile is triggered. There are possible pools for data, voice and SMS usage.

{
  "time": "2025-08-02T09:54:13.133Z",
  "id": "00000000-0000-1000-a000-000708986526",
  "source": "/notification/poollimit",
  "specversion": "1.0",
  "type": "poollimitnotification.v1",
  "datacontenttype": "application/json",
  "data": {
    "partnerID": "162652",
    "poolLimitNotification": {
      "poolName": "SMS Test Pool",
      "offeringName": "Test Pool PLS",
      "offeringID": 800206106,
      "typeOfThreshold": "SMS Limit 1",
      "limit": 50.0,
      "date": "2025-08-02T09:43:11.142Z"
    }
  }
}
Example event of a reached level 1 of a SMS pool limit.

Parameter
Data Type
Description
data
object
Specific payload of the event
datacontenttype
string
MIME type of the response
date
string
Date and time when the limit level has been reached (UTC timestamp)
id
string
Event ID
limit
number
Percentage of the pool defined for the corresponding limit level
offeringID
number
ID of the corresponding partner level service
offeringName
string
Name of the corresponding partner level service
partnerID
string
Partner ID of the customer
poolLimitNotification
object
Information about the pool limit notification
poolName
string
Name of the defined pool
source
string
Source of the event
specversion
string
Current specifications version
time
string
UTC timestamp of the event
type
string
Event type
typeOfThreshold
string
Type and level of the reached pool limit ("Data", "Voice", "SMS"; for each "Level 1" or "Level 2")

Cost Limit Notification

A Cost Limit Notification is provided when a limit level of an assigned cost limit profile is triggered. There are possible cost limits for voice and SMS usage.

{
   "time": "2025-08-02T09:54:13.133Z",
   "id": "00000000-0000-1000-a000-000708986526",
   "source": "/notification/costlimit",
   "specversion": "1.0",
   "type": "costlimitnotification.v1",
   "datacontenttype": "application/json",
   "data": {
      "partnerID": "162652",
      "costLimitNotification": {
         "iccid": "8925475978255758883",
         "euiccid": "22233356789100043",
         "imsi": "254759782866388",
         "msisdn": "4367619128340",
         "offeringName": "Test SLS",
         "offeringID": 800000333,
         "typeOfThreshold": "SMS Limit 1",
         "limit": 25,
         "date": "2025-08-02T09:43:11.142Z",
         "profileName": "Test Cost Limit Profile",
         "profileID": 708529655
      }
   }
}
Example event of a reached level 1 of a SMS cost limit.

Parameter
Data Type
Description
costLimitNotification
object
Information about the cost limit notification
data
object
Specific payload of the event
datacontenttype
string
MIME type of the response
date
string
Date and time when the limit level has been reached (UTC timestamp)
euiccid
string
eUICCID of the SIM card
iccid
string
ICCID of the SIM card
id
string
Event ID
imsi
string
IMSI of the SIM card
limit
number
Cost limit as defined in the cost limit profile for the corresponding limit level
msisdn
string
MSISDN of the SIM card
offeringID
number
ID of the corresponding SIM level service
offeringName
string
Name of the corresponding SIM level service
partnerID
string
Partner ID of the customer
profileID
number
ID of the cost limit profile
profileName
string
Name of the cost limit profile
source
string
Source of the event
specversion
string
Current specifications version
time
string
UTC timestamp of the event
type
string
Event type
typeOfThreshold
string
Type and level of the reached cost limit ("Voice", "SMS"; for each "Level 1" or "Level 2")

Frequently Asked Questions

1.   Authentication & Security

How do I create an API key?

Booking the optional "REST API" service is a prerequisite. As an administrator of an M2M Service Portal 3.0 account, you will find a "REST API" tab under "My Partner Data". There, you can register new applications. One application corresponds to one API user with an IRIS Client ID and Client Secret.

Do source IPs need to be whitelisted for REST API access?

For security reasons, you can restrict API communication to up to 10 specific IP addresses (IP Whitelisting) during application registration.

If no whitelist is defined, there are no restrictions, and the API can be accessed from any source IP.

Is 2FA available for the REST API in addition to IP whitelisting?

No, there is currently no standard 2FA option for REST API access.

How do I create a Bearer Token?

Access tokens are issued via the Deutsche Telekom AG Token Issuer URL: https://sg-api.telekom.de. Further details can be found in the Getting Started section.

curl --request POST \
--url "https://sg-api.telekom.de/auth/realms/default/protocol/openid-connect/token" \
--header "Accept: application/json" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret&scope=openid"
Example token request via cURL.

How long is a token valid, and how does the refresh work?

A token is valid for approximately 300 seconds. After expiration, a new token must be requested.

Is there a Postman collection available?

You can export the OpenAPI/Swagger definition (see the link at the top right corner of this page) and import it directly into Postman to generate your own collection.

2.   Connectivity & SIM Management

Can I manage all M2M Service Portal 3.0 business transactions via REST API?

The GUI and REST API can be used in parallel. However, while the GUI is the central control tool, the REST API and automated reports are designed for specific automation use cases. Therefore, not all GUI business transactions can be run via REST API.

How can I retrieve a list of ICCIDs, IMSIs, and credentials (PIN/PUK) that were delivered after a SIM order?

The REST API only returns a confirmation of the successful workflow for SIM orders.

SIM-specific data (ICCIDs, etc.) is provided as a list/.csv file via Standard Reports. For automation, you can book the "Automated Standard Report Delivery" via sFTP (Data Hub/DDS). Please contact your IoT sales representative.

Can I send Wake-up SMS via REST API to reactivate devices from standby?

The M2M Service Portal 3.0 does not include a "Large Account SMS" by default; this is a separate product which can be used e.g. for bulk wake-ups.

For individual SIM diagnostics, the Send Message method can be used. This is not suitable for mass SMS or bulk wake-ups.

Why do GET methods only use ICCID as an identifier instead of IMSI or MSISDN?

We consider IMSI and MSISDN sensitive attributes. Since GET parameters are transmitted in the URL, we use POST methods for these identifiers to ensure data security.

Why are most operations handled via POST instead of standard REST conventions (GET, PUT, DELETE)?

In several cases, data privacy and security requirements took priority over strict REST notation.

How do I access SIMs in a Subunit via REST API?

Subunits are identified by their own Partner ID. Access to Subunit SIMs must always use that dedicated Partner ID. It is not possible to access Subunit SIMs using a Superunit Partner ID, ensuring autonomous access within Subunits.

How can I track SIM status changes (e.g. from 'Ordered' to 'Delivered' or 'Active')?

Most status changes are customer-initiated and thus known to your system. They are only partially available as events. Current SIM status is provided daily in the Standard Report.

How can I retrieve a list of my Data Access Profiles (DAPs) and the corresponding IDs via REST API?

The creation and configuration of Data Access Profiles typically occur prior to process automation. Therefore, a feature to retrieve, create, or modify DAPs via the REST API is currently not available. These actions must be performed through the GUI. There you can collect the IDs and use them for parametrization in your requests.

Can I include multiple SIMs in a request?

That depends on the API call: You find the capability per method in chapter 2 of the Getting Started section. Under "Possible SIM Card Identifiers" the SIM quantity is stated as single or bulk.

What is the maximum bulk size to be used within SIM bulk enabled API methods?

The maximum number of SIMs within a bulk request is 1000 SIMs.

What is the difference between activating SIMs individually and using a bulk activation via the REST API?

If all SIMs can be activated successfully, the outcome is the same for both approaches. However, differences occur if one or more SIMs cannot be activated:

  • Per SIM activation (multiple single requests): Only the SIMs that fail are not activated. All others are processed successfully.
  • Bulk activation: If any SIM in the request fails, the complete request is rejected and no SIMs are activated.

Does "multiple identifier support" mean the same as multiple SIMs?

"Multiple identifier support" means you can use a different parameter than ICCID like eUICCID, IMSI, IMEI etc. to address a SIM. However, if the method in chapter 2 of the Getting Started section states "SIM Quantity" as "single", only one SIM can be addressed.

How can I use global network control functions via REST API?

Advanced network features such as Local Breakouts (LBO) and Network Preference settings are currently not available via the REST API.

Which SIM status values can I retrieve via the REST API?

Using the REST API (e.g. via "Get SIM Details"), you can retrieve the logical SIM status. This status is consistently used across the API, the user interface, and reporting in the M2M Service Portal 3.0.

The following status values may be returned (in English – for detailed explanations of each status, please refer to the M2M Service Portal 3.0 documentation):

  • Ordered
  • On Stock
  • Delivered
  • Test
  • Productive
  • Blocked (automatically)
  • Blocked (manually)
  • Suspended
  • Terminated
  • Deleted
  • Undefined
  • Ordered for stock
  • Special Terminated
  • Blocked (MNO)

3.   Tariffs & Quotas

How can I query the remaining binding contractual period for a SIM via API?

The SIM Details method provides information on the "bindingPeriod". For more detailed contract data, please use the automated Standard Reports via sFTP.

{
  "SimDetails": {
    "iccid": "8999829698800414538",
    "imsi": "998296987729336",
    (...)
    "bindingPeriod": "2026-05-31",
    "offering": "Tariff 3",
    "accessProfile": "720378456",
    (...)
  }
}
Excerpt of a SIM Details response with the "bindingPeriod" parameter.

I tried to activate a SIM in a Subunit with a tariff via API but it failed. Why?

Have you ensured that the tariff can be used within the Subunit? You need to grant the tariff usage per Subunit via your M2M Service Portal 3.0 GUI. Please have in mind that some tariffs (e.g. Data Best) can not be used for SIMs in Subunits.

Can I monitor the data consumption of my SIMs in my IT system in near real-time?

For individual SIMs, you can retrieve aggregated session volumes via "simAggregatedData" within the SIM Details method. Note: The Session Volumes feature is not available for all NB-IoT customers.

Please note that these values are indicative only. Aggregated session data does not correspond 1:1 to the billing-relevant data volumes (CDRs) based on tariff logic. If you require near real-time UDRs you may rely on the optional "Automated Delivery of Usage Data Records" via sFTP (Data Hub/DDS). If you require billing-relevant CDRs, please use the optional "Automated Standard Report Delivery" via sFTP (Data Hub/DDS).

My application faces a 403 "Limit Exceeded" error – how can I avoid this or increase the limit?

Please check the limits stated in chapter 4 of the Getting Started section. Limits are fixed and calculated over 6-minute intervals based on the number of SIM requests fired (not the number of method calls). Please adjust your request frequency accordingly.

4.   Actions & Event Handling

Are Webhooks offered for callbacks in addition to Server-Sent Events (SSE)?

Deutsche Telekom AG focuses on Server Sent Events (SSE) as it offers a near real time event provisioning without firewall/security limitations for callbacks like Webhooks do for most corporates.

Which events are supported?

A list of supported SIM actions and notifications can be found directly in the section Event Documentation.

Is there a notification when a SIM status changes from "Test" to "Productive"?

Such tariff changes are not currently included in the notifications.

5.   Troubleshooting & Support

Is there a test environment (Sandbox) with simulated SIMs?

Deutsche Telekom AG does not provide a fully isolated sandbox for the M2M Service Portal 3.0 REST API. To test your software during a staging process, we recommend:

  1. Using dedicated API users restricted to specific Subunits
  2. Limiting API user roles to "read-only" for tests
  3. Restricting full-scale tests to selected test ICCIDs.

Who can support me with onboarding or specific questions about my custom solution?

Consulting is available as an optional professional service upon request. Please contact your IoT sales representative.

Can new REST API methods be developed to meet my specific needs?

Development of customer specific methods may be possible upon individual, project-based request. Please contact your IoT sales representative.

Why are some error codes generic or not compliant with REST RFC standards?

Currently, error codes for REST API v1 are not centrally managed. For example, rate-limiting currently triggers a 403 Forbidden instead of the standard 429 Too Many Requests.

These discrepancies will not be changed in v1 to maintain backward compatibility but will be addressed in upcoming versions.

Version History

3.8.5

3.8.4

  • Added SIM Change Tariff upgrade feature.

3.8.1

  • Added the possibility to accept a SIM Transfer with the receiving partner being a subunit.
  • Added new optional parameter subunitPartnerID to Update SIM Transfer.
  • Added new element subunitPartnerID to the Get SIM Transfer Details response.

3.7.12

  • The resources Get API Usage and Check SIM in HLR are deprecated for technical reasons.

3.7.11

  • Added information about server sent events in Getting Started and a new tab with further information.

3.7.9

  • SIM Unrestrict supports APN specific unrestriction.

3.7.8

  • Introduced the resource SIM Book Option.
  • Introduced the resource SIM Terminate Option.

3.7.7

  • Introduced the resource SIM Change Option.

3.7.5

  • Introduced new POST requests to make more SIM card identifiers like eUICCID (eID), IMSI, IMEI (IMEISV) or MSISDN available, depending on the request or type and status of the SIM card(s). See more details in the section Getting Started.
  • New POST requests are: Get SIM Details, Get SIM Session, Get SIM Session History, Get SMS History, Check SIM in HLR, Reset SIM in HLR.

3.7.4

  • Added specified peak request rate in section Protective Measures.

3.7.2

  • Added new element euiccid to the Get SIM List response.
  • Improved displaying of POST request examples by merging the schema example and individually documented request examples into a dropdown element of the Request Body section.

3.7.1

  • Introduced the resource Bind eUICCID to bind or unbind eUICCIDs (eIDs) to SIM cards.
  • Added element eidProfileStatus to the Get SIM Details response.

3.6.11

  • Added element simAggregatedData to the Get SIM Details response.

3.6.10

  • Added new optional parameter parallelSessions to Get SIM Sessions.
  • When set to true it changes the response to show multiple sessions of the SIM card, if this service is booked.

3.6.5

  • Changed all occurrences of actionId to signupId, to unitize parameters which are technically equivalent.
  • Added new element signupId to the Get SIM Action List response.

3.6.4

  • Added new flag overrideMoq for SIM Order to override the minimum order quantity of a SIM material.
  • Added new element activationCode to the SIM Details response, which shows the activation code of a SIM card (if available) when the order process is completely finished.

3.6.3

  • Added new elements network, sessionStart, volumeUpload, volumeDownload and volumeRounded to the Get SIM Session response.

3.6.2

  • Added new additional element staticIpsPerApn to the request body of SIM Modify Profiles.
  • Added new element bindingPeriod to the Get SIM Details response.

3.6.1

  • Introduced the resource Get Current Pool Usage.
  • Parameters dateFrom and dateTo in Get SMS History changed to optional.
  • Result of Get SIM Action Status now contains a link to SIM Action Cancellation in case the action can be cancelled.
  • Added restrictionReason to the responses of Get SIM Session and Get SIM Session History.

3.5.11

  • Introduced the resource for Get SIM Action List.

3.5.9

  • Introduced the resource for /partners/{partnerID} which retrieves the amount of SIM cards in specific states for the requested customer.

3.5.8

  • Introduced the resources for Check SIM in HLR and Reset SIM in HLR.
  • Added information about data consumption in SIM List.

3.5.6

  • Introduced the resources for Enter Productive State, Restore Limit Status, Reset Limit Status and Reset Fraud Status.

3.5.4

  • Go Live of productive Customer REST API.

3.5.3

  • Added SIM Options to the SIM Details.
  • Introduced the resources for SIM Restrict and SIM Unrestrict (optional services).

3.5.2

  • Introduced the resource Send Message.

3.5.1

  • Added the attributes SIM restriction, limit status and fraud status to the SIM Details.
  • Introduced defaults for the timespan in the Session History.

3.4.11

  • Introduced the resource Create SIM Order.