APIs Device to Cloud UDP Devices Onboard devices

UDP Device provisioning request

Devices are represented as node instances in oneM2M. You can request to onboard a list of nodes by adding a “/device-provisioning/request”:

  • Request
  • Response
POST {{API_URL}}/device-provisioning/request HTTP/2
Accept: application/json
Content-Type: application/json;ty=28
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
    "dtiot:noPRt": {
        "cnd": "com.telekom.iot.orchestrator.nodeProvisioningRequest",
        "rn": "myUDP-DeviceProvisioningRequest",
        "opern": 1,
        "reqLt": [
            {
                "ni" : "urn:gsma:imei:999907050041452",
                "noRNe": "myUDP-Device01",
                "profe" : "SCS-UDP",
                "lbl": [
                  "Location:13509 Berlin, Holzhauser Str 4-8, Building A",
                  "d2c-uplink-property_AssetId:1234543",
                  "d2c:1.0"
                ],
                "nodeDeviceGroups": [],
                "ndvi": {
                    "rn": "device-info",
                    "mgd": 1007,
                    "man": "some manufacturer",
                    "dty": "some device type",
                    "mod": "some model",
                    "dlb": "some:label",
                    "dc": "a comment"
                }
            }
        ]
    }
}

HTTP/1.1 201 Created
date: Fri, 22 May 2026 08:55:26 GMT
content-type: application/json; charset=utf-8
request-context: appId=cid-v1:
x-service-responder: device-management-orchestrator
x-m2m-ri: 123
x-m2m-rvi: 4
x-m2m-ot: 2026-05-22T08:55:26.304Z
x-m2m-rsc: 2001
x-azure-ref: 20260522T085526Z-157794674c588bv2hC1FRAqubc0000000yng00000000nr1d
x-cache: CONFIG_NOCACHE
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
x-content-type-options: nosniff
x-frame-options: DENY
x-xss-protection: 0
referrer-policy: no-referrer
x-tardis-traceid: e02c1daad6529714d14a233132313436
vary: Origin
x-kong-upstream-latency: 138
x-kong-proxy-latency: 2
x-kong-request-id: c124506370a5fa4ad225a547eea42631
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 994
x-http2-stream-id: 3
{
  "dtiot:noPRt": {
    "cnd": "com.telekom.iot.orchestrator.nodeProvisioningRequest",
    "rn": "myUDP-DeviceProvisioningRequest",
    "opern": 1,
    "reqLt": [
      {
        "ni": "urn:gsma:imei:999907050041452",
        "noRNe": "myUDP-Device01",
        "profe": "SCS-UDP",
        "lbl": [
          "Location:13509 Berlin, Holzhauser Str 4-8, Building A",
          "d2c-uplink-property_AssetId:1234543",
          "d2c:1.0"
        ],
        "ndvi": {
          "rn": "device-info",
          "mgd": 1007,
          "man": "some manufacturer",
          "ty": "some device type",
          "mod": "some model",
          "dlb": "some:label",
          "dc": "a comment"
        },
        "nodeDeviceGroups": []
      }
    ],
    "ty": 28,
    "cr": "CmyApplication",
    "st": 0,
    "ri": "67...2a",
    "pi": "67...3f",
    "ct": "20241121T091747,984000",
    "lt": "20241121T091747,984000"
  }
}

Parameters:

  • In Content-Type header: ty=28 means “flexContainer”
  • cnd - containerDefinition — contains an identifier reference (URI) to the “flexContainer” schema definition which shall be used by the CSE to validate the syntax of the FlexContainer resource
  • operation: 1=provision
  • requestList: Array of “node” instances with
    • nodeID: The value shall be a valid nodeID string in the format: urn:gsma:imei:<imei>
    • nodeResourceName: This is the “Device ID” which e.g. is used in Device Groups to identify the device.
    • profile: Defines the IoT platform where the device is onboarded. For UDP Devices use SCS-UDP.
    • lbl: An array of strings. The label "d2c:1.0" is mandatory for “Device to Cloud” IoT devices. Example: ["Location:Berlin","d2c-uplink-property_AssetId:123","d2c:1.0"]
    • nodeDeviceGroups (optional): An array containing a list of groups where the device should be added.
    • ndvi (optional): Device-related information (manufacturer, device type, model, etc.)
  • X-M2M-RI: Represents a unique request ID. Please don’t use 123! If you have a support request you can help us by providing us the related request ID.
Note:
Unlike LwM2M devices, UDP devices do not require nodeCredentials (PSK). The platform identifies UDP devices by their SIM card (IMEI) via the Telekom mobile network.

What happens during provisioning

The provisioning request for UDP devices (profile: SCS-UDP) triggers the following actions on the platform:

  1. Device node and containers — the device node and all required message containers (received-msg, sent-msg, outgoing-msg, error-msg) are created in DMO.
  2. IMEI-to-tenant mapping — the platform registers the device IMEI so that incoming uplink traffic is routed to the correct tenant.
  3. Uplink properties — the platform stores the custom uplink properties (derived from d2c-uplink-property_ labels) so they can be included in every uplink message.

Get a device by IMEI

  • Request
  • Response
GET  {{API_URL}}?rcn=4&ty=13&ty=14&ni=urn:gsma:imei:999907050041452 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
date: Mon, 25 May 2026 16:17:57 GMT
content-type: application/json; charset=utf-8
request-context: appId=cid-v1:
x-service-responder: device-management-orchestrator
x-m2m-ri: 123
x-m2m-rvi: 4
x-m2m-ot: 2026-05-25T16:17:57.858Z
x-m2m-rsc: 2000
x-azure-ref: 20260525T161757Z-r1d8c8b4b7f8ncs4hC1FRA2s6w0000000ew000000000ayuk
x-cache: CONFIG_NOCACHE
accept-ranges: bytes
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
x-content-type-options: nosniff
x-frame-options: DENY
x-xss-protection: 0
referrer-policy: no-referrer
x-tardis-traceid: 486cbd34bf187c63cf1c233133343239
vary: Origin
x-kong-upstream-latency: 212
x-kong-proxy-latency: 2
x-kong-request-id: 91e1eb0ae1fb9709414f46607ce4164f
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 504
x-http2-stream-id: 3

{
  "m2m:nod": {
    "ni": "urn:gsma:imei:999907050041452",
    "lbl": [
      "Location:64295 Darmstadt, Deutsche Telekom Allee 9, Building D",
      "d2c-uplink-property_AssetId:Asset-12345",
      "d2c:1.0",
      "profile:SCS-UDP"
    ],
    "rn": "myUDP-Device01",
    "ty": 14,
    "ct": "20260326T111645,756000",
    "pi": "myTenant",
    "ri": "69c5159dcb8c0f35bdf06da0",
    "lt": "20260326T111645,756000"
  }
}

Error handling

If an error occurs during provisioning/handling CRUD operations with device, It will be written to error-msg and logs containers. error-msg container is belonged to particular device, while logs container is shared for all devices.
The error message contains the details of the error, such as error code, error message, error details and device identifier.

Example of error message in error-msg container for a particular device

  • Request
  • Response
GET {{API_URL}}/device-communication/myUDP-Device01/error-msg/la HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
date: Mon, 25 May 2026 16:17:57 GMT
content-type: application/json; charset=utf-8
request-context: appId=cid-v1:
x-service-responder: device-management-orchestrator
x-m2m-ri: 123
x-m2m-rvi: 4
x-m2m-ot: 2026-05-25T16:17:57.858Z
x-m2m-rsc: 2000
x-azure-ref: 20260525T161757Z-r1d8c8b4b7f8ncs4hC1FRA2s6w0000000ew000000000ayuk
x-cache: CONFIG_NOCACHE
accept-ranges: bytes
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
x-content-type-options: nosniff
x-frame-options: DENY
x-xss-protection: 0
referrer-policy: no-referrer
x-tardis-traceid: 486cbd34bf187c63cf1c233133343239
vary: Origin
x-kong-upstream-latency: 212
x-kong-proxy-latency: 2
x-kong-request-id: 91e1eb0ae1fb9709414f46607ce4164f
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 504
x-http2-stream-id: 3

{
  "m2m:cin": {
    "con": {
      "nodeResourceName": "myUDP-Device01",
      "nodeID": "urn:gsma:imei:999907050041452",
      "data": "",
      "status": {
        "code": 500,
        "message": "internal server error",
        "detail": "Internal server error: subscription creation failed."
      }
    },
    "cnf": "application/json:0",
    "ty": 4,
    "cs": 604,
    "st": 3,
    "cr": "CmyApplication",
    "rn": "a2efd14b-d5d8-41e0-9c3c-74e907abfc95",
    "ri": "69b17f068006f89d59522af0",
    "pi": "69b132f78006f89d59521efa",
    "ct": "20260311T144110,154000",
    "lt": "20260311T144110,154000"
  }
}

Fields:

  • nodeResourceName — the device ID as registered during provisioning.
  • nodeID — the IMEI-based node identifier (urn:gsma:imei:<imei>).
  • data — empty in case of errors not related to messages.
  • status.code — HTTP-style error code
  • status.message — short error description.
  • status.detail — detailed error message for debugging.
  • cnf — content format; "application/json:0" indicates a JSON payload.

Example of error message in logs container

  • Request
  • Response
GET {{API_URL}}/device-provisioning/logs/la HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CmyApplication
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
date: Mon, 25 May 2026 16:17:57 GMT
content-type: application/json; charset=utf-8
request-context: appId=cid-v1:
x-service-responder: device-management-orchestrator
x-m2m-ri: 123
x-m2m-rvi: 4
x-m2m-ot: 2026-05-25T16:17:57.858Z
x-m2m-rsc: 2000
x-azure-ref: 20260525T161757Z-r1d8c8b4b7f8ncs4hC1FRA2s6w0000000ew000000000ayuk
x-cache: CONFIG_NOCACHE
accept-ranges: bytes
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
x-content-type-options: nosniff
x-frame-options: DENY
x-xss-protection: 0
referrer-policy: no-referrer
x-tardis-traceid: 486cbd34bf187c63cf1c233133343239
vary: Origin
x-kong-upstream-latency: 212
x-kong-proxy-latency: 2
x-kong-request-id: 91e1eb0ae1fb9709414f46607ce4164f
strict-transport-security: max-age=31536000; includeSubDomains
content-length: 504
x-http2-stream-id: 3

{
  "m2m:cin": {
    "con": {
      "identifier": "urn:gsma:imei:999907050041452",
      "type": "device processing failed",
      "service": "d2c-device-provisioning",
      "data": "",
      "status": {
        "code": 400,
        "message": "bad request",
        "detail": "device event could not been handled. Check the data of device. profile is missed."
      }
    },
    "cnf": "application/json:0",
    "ty": 4,
    "cs": 641,
    "st": 2,
    "cr": "CmyApplication",
    "rn": "31af43c7-f111-4e5a-9694-7c66f5745f72",
    "ri": "69b17f068006f89d59522af1",
    "pi": "69b158c08006f89d595224b4",
    "ct": "20260311T144110,172000",
    "lt": "20260311T144110,172000"
  }
}

Fields:

  • identifier — the IMEI-based node identifier (urn:gsma:imei:<imei>).
  • type — describes the error category (e.g. "device processing failed").
  • service — the service that produced the log entry (d2c-device-provisioning).
  • data — empty in case of errors not related to messages
  • status.code / status.message / status.detail — same semantics as in the error-msg container.
  • cnf — content format; "application/json:0" indicates a JSON payload.

Errors summary table

Status CodeStatus MessageDescription
400bad requestUDP device could not been provisioned. Check the data of device-provisioning request. imei is missed.
400bad requestUDP device could not been provisioned. Check the data of device-provisioning request. imei has invalid format.
400bad requestDevice could not been provisioned. Check the data of device-provisioning request. nodeResourceName is missed.
400bad requestDevice could not been provisioned. Device with the same nodeResourceName already exists.
400bad requestdevice event could not been handled. Check the data of device. profile is missed.
400bad requestDevice could not been provisioned. Check the data of device-provisioning request. profile is missed.
500internal server errorInternal server error: subscription creation failed.
500internal server errorInternal server error: device-provisioning unable to get device data.
500internal server errorInternal server error: device-provisioning unable to create device objects.
500internal server errorInternal server error: device-provisioning unable to create device data.
500internal server errorInternal server error: device-provisioning unable to remove device subscription.
500internal server errorInternal server error: device-provisioning unable to create device subscription.
500internal server errorInternal server error: device-provisioning unable to create device data in table.
500internal server errorInternal server error: unexpected error occurred.
500internal server errorInternal server error: device-provisioning unable to update device data.
500internal server errorInternal server error: device-provisioning unable to update device properties.
500internal server errorInternal server error: device-provisioning unable to get device data from table.
500internal server errorInternal server error: device-provisioning unable to update device data in table.
500internal server errorInternal server error: device-provisioning unable to delete device data.
500internal server errorInternal server error: device-provisioning unable to process notification data.

Next step

Start sending data to your UDP device and receive data back from the device.