Migrating from Gen1 to the Gen2 API

Last updated September 15th, 2025

This guide covers how to migrate from Knox Deployment Program (KDP) Gen1 API to Gen2 API, which is the latest generation. The Gen2 API features restructured endpoints to simplify your workflow and enhance security.

Server URL change

For the migration, the following Gen1 API servers must be whitelisted in your network firewall:

  • https://eu-be-reseller.samsungknox.com (EU server)
  • https://us-be-reseller.samsungknox.com (US server)

To the following server will be used instead for Gen2, which also needs to be whitelisted in your firewall:

  • https://api.samsungknox.com/kcs/v1/rp (global server)

During migration or development, please use the new Gen2 server URL to test the APIs. You can stop using the Gen1 server URL once your Gen2 solution is live.

Authentication changes

To authenticate Gen2 API calls, you need to:

API message payload and response format changes

For overall mapping of Gen1 API to Gen2, please read the REST API Comparison section in this article.

Differences in Gen1 and Gen2 request payloads and response formats are described below.

For upload/delete device

In Gen1:

    {
      "transactionId": "244303",
      "resellerId": "468....925",
      "customerId": "12....321",
      "transactionType": "New",
      "devices": {
        "type": "IMEI",
        "list": ["35180000....702"
        ]
      }
    }

In Gen2, transactionType has been removed (now identified by endpoint), and type has been moved to the parent level:

    {
      "transactionId": "244303",
      "resellerId": "460....925",
      "customerId": "12....321",
      "type": "IMEI",
      "devices": [
        "35182610....702"
      ]
    }

For list devices

In Gen1:

    {
      "totalCount": 0,
      "totalPage": 0,
      "pageNum": 0,
      "devices": [{
        "imei": "35719261....112"
      }]
    }

In Gen2, totalPage was changed to totalPages, which additionally includes new fields:

    {
      "code": "2000000",
      "message": "SUCCESS",
      "pageNum": 0,
      "pageSize": 1000000,
      "totalCount": 0,
      "totalPages": 0,
        "size": 0,
        "devices": [{
          "id": "6012afe85f18342e67ee9126",
          "createTime": 1611837416372,
          "mei": "35182600....702",
          "customerName": "Demo-Customer",
          "customerId": "460....586",
          "serialNumber": "R3OO....KLD",
          "meid": "08907750000....280",
          "model": "SM-G981B/DS",
          "state": "Verified",
          "uploadId": "ddb71b6c-3aef-4d54-b1f4-b86480aa447d"
        }]
    }

For check transaction status message

In Gen1:

    {
      "totalCount": 2,
      "totalPage": 1,
      "pageNum": 0,
      "transactions": [{
        "transactionId": "7500657464",
        "state": "Complete",
        "type": "Put",
        "devices": [{
          "imei": "80721262....673"
        }, {
          "imei": "2197517....444"
        }, {
          "imei": "4064950....126",
          "code": 4092100,
          "message": "RESELLER_DEVICE_ALREADY_EXISTS",
          "data": "device imei[09743614....341] already exists"
        }]
      }]
    }

In Gen2, everything now appears within a new devices object:

      {
        "devices": {
          "totalCount": 1,
          "totalPage": 1,
          "pageNum": 0,
          "transactions": [{
            "transactionId": "246903",
            "state": "Complete",
            "type": "Put",
            "operationType": "UPLOAD",
            "devices": [{
              "imei": "35182611....643",
              "code": 40000004,
              "message": "DEVICE_INVALID",
              "data": "The specified device is not valid."
            }]
          }]
        }
      }

The inner devices object contains information about failed transactions. If none of the transactions failed, it will not be included in the response — as below:

      {
        "devices": {
          "totalCount": 1,
          "totalPage": 1,
          "pageNum": 0,
          "transactions": [{
            "transactionId": "248603",
            "state": "Complete",
            "type": "Put",
            "operationType": "UPLOAD"
          }]
        }
      }

Is this page helpful?