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"
}]
}
}
On this page
Is this page helpful?