Device Management API: bulk operations via CSV file upload

This document provides a detailed step-by-step description of how to use the Bulk Device Activation and Device Group Assignment API

API Endpoint: /v1/api/hss/activation-from-file

The API accepts a CSV file containing device information and a specific operation code [op_code] based on the intended use case.

Device Activation and Device Group Assignment

Mandatory - ICCID
- Activation will fail if ICCID is not specified
Optional - DEVICE_NAME & DEVICE_GROUP
- The device name will be applied only for the ICCIDs which succeeded in device activation.
- The device is assigned to the default device group if no DEVICE_GROUP is specified.
Following optional fields are available to support sim lock configurations for each device:
- Optional - SimLockStatus
  - string
  - “Enabled” for enabling sim lock
  - “Disabled” or ““ for disabling sim lock
- Optional - SimLockPolicy
  - string
  - "ONATTACH"
  - "IMEIMAPPING"
- Optional - SimLockExpectedIMEI
  - string
  - IMEI if IMEIMAPPING has been set as SimLockPolicy
Op Code: ACTIVATE_AND_DG_ASSIGN
Note - Starting with 2311, CLUSTER_NAME in the CSV will be ignored because of the change in device activation workflow. Device and Edge cluster association is now defined by the network control policy(s) of the device group to which the device belongs

Device Activation

Mandatory - ICCID
- Activation will fail if ICCID is not specified.
Optional - DEVICE_NAME
- The device name will be applied only for the ICCIDs which succeeded in device activation.
Following optional fields are available to support sim lock configurations for each device:
- Optional - SIMLOCKSTATUS
  - string
  - “Enabled” for enabling sim lock
  - “Disabled” or ““ for disabling sim lock
- Optional - SIMLOCKPOLICY
  - string
  - "ONATTACH"
  - "IMEIMAPPING"
- Optional - SIMLOCKEXPECTEDIMEI
  - string
  - IMEI if IMEIMAPPING has been set as SimLockPolicy
Op Code: ACTIVATE
Note - Starting with 2311, CLUSTER_NAME in the CSV will be ignored because of the change in device activation workflow. Device and Edge cluster association is now defined by the network control policy(s) of the device group to which the device belongs

Device Group Assignment

Mandatory - ICCID
Optional - DEVICE_GROUP (name of the device group)
- The device is assigned to the default device group if no DEVICE_GROUP is specified.
Op Code: DG_ASSIGN
Note - Starting with 2311, CLUSTER_NAME in the CSV will be ignored because of the change in device activation workflow. Device and Edge cluster association is now defined by the network control policy(s) of the device group to which the device belongs

The API also handles failure causes without defaulting to ‘fail for all,’ which means:

devices with valid ICCIDs will proceed with the operation
devices with invalid ICCIDs will be added to the failed list of devices and displayed as part of the failure response.

Note

CSV parsing is position based, hence it is expected that the order specified above is strictly followed.
Sim lock fields above are optional and don’t have to be provided.
If sim lock fields are not provided, the device will be activated with sim lock disabled.

API call example

curl --location 'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=<Operation Code>'  
--header 'Content-Type:  multipart/form-data; boundary=<calculated when request is sent>' --header 'x-api-key: ‘<API_KEY>’ 
--header 'Accept: */*' --form 'simDataFile=@"/<path_to_file>/act_data.csv"'

API Sample Response for successful device activation and device group assignment

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=ACTIVATE_AND_DG_ASSIGN

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP 
89105212033100003477,Cluster123,Tom's Macbook,TestDeviceGroup 
89105212033100003478,Cluster123,Jane's iPhone,TestDeviceGroup 
89105212033100003479,Cluster123,Dan's iPad,TestDeviceGroup

Response:

{ 
  "data": { 
    "failed_devices": null, 
    "successful_devices": [ 
      { 
        "action": "DEVICE_ACTIVATION", 
        "iccids": [ 
          "89105212033100003477", 
          "89105212033100003478", 
          "89105212033100003479" 
        ] 
      }, 
      { 
         “action”: “DEVICE_NAME_UPDATE”,
         “iccids”: [ 
           “89105212033100003474”,
           “89105212033100003476”
         ]       
       },
      { 
        "action": "DEVICE_GROUP_ASSIGNMENT", 
        "iccids": [ 
          "89105212033100003477", 
          "89105212033100003478", 
          "89105212033100003479" 
        ] 
      } 
    ] 
  }, 
  "responseMeta": { 
    "code": 200, 
    "error": "", 
    "success": true 
  }

API Sample Response for successful device activation

Request :

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=ACTIVATE

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP 
89105212033100003474,Cluster123,Tom's Macbook,TestDeviceGroup 
89105212033100003475,Cluster123,Jane's iPhone,TestDeviceGroup 
89105212033100003476,Cluster123,Dan's iPad,TestDeviceGroup

Response:

{ 
  “data”: { 
    “failed_devices”: null, 
    “successful_devices”: [ 
      { 
        “action”: “DEVICE_ACTIVATION”, 
        “iccids”: [ 
          “89105212033100003474”, 
          “89105212033100003475”, 
          “89105212033100003476” 
        ] 
      },
      {
         “action”: “DEVICE_NAME_UPDATE”,
         “iccids”: [ 
           “89105212033100003474”,
           “89105212033100003476”
         ]       
       }
     ]
  }, 
  “responseMeta”: { 
    “code”: 200, 
    “error”: “”, 
    “success”: true 
  } 
}

Successful Device Group Assignment -

Request :

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=DG_ASSIGN

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_GROUP 
89105212033100003474,Cluster123,TestDeviceGroup 
89105212033100003475,Cluster123,TestDeviceGroup 
89105212033100003476,Cluster123,TestDeviceGroup

Response:

{ 
  "data": { 
    "failed_devices": null, 
    "successful_devices": [ 
      { 
        "action": "DEVICE_GROUP_ASSIGNMENT", 
        "iccids": [ 
          "89105212033100003474", 
          "89105212033100003475", 
          "89105212033100003476" 
        ] 
      } 
    ] 
  }, 
  "responseMeta": { 
    "code": 200, 
    "error": "", 
    "success": true 
  } 
}

API Sample Responses for failures

Mismatched Columns - CSV File Errors (FILE_IO) -

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=<any_op_code>

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP
891052120331000034772305,Cluster123,Tom’s iPhone,TestDeviceGroup

Response:

{ 
  "data": { 
    "failed_devices": [ 
      { 
        "action": "FILE_IO", 
        "file_records": [ 
          "89105212033100003477Cluster123 TestDeviceGroup" 
        ], 
        "reason": "Corrupted Record" 
      } 
    ], 
    "successful_devices": null 
  }, 
  "responseMeta": { 
    "code": 200, 
    "error": "", 
    "success": true 
  } 
}

Duplicate ICCID Records - CSV File Errors (FILE_IO)

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=<any_op_code>

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP 
89105212033100003481,Cluster123,Jane's iPad,TestDeviceGroup 
89105212033100003481,Cluster123,Jane's iPad,TestDeviceGroup

Response:

{ 
  "data": { 
    "failed_devices": [ 
      { 
        "action": "FILE_IO", 
        "file_records": [ 
          "89105212033100003481 Cluster123 TestDeviceGroup" 
        ], 
        "reason": "Duplicate ICCID records in the CSV, 1st occurrence has been processed" 
      } 
    ], 
    "successful_devices": [ 
      { 
        "action": "DEVICE_ACTIVATION", 
        "iccids": [ 
          "89105212033100003481" 
        ] 
      }, 
      {         
         "action": "DEVICE_NAME_UPDATE",  
         "iccids": [           
           "89105212033100003481"         
         ]
       },
      { 
        "action": "DEVICE_GROUP_ASSIGNMENT", 
        "iccids": [ 
          "89105212033100003481" 
        ] 
      } 
    ] 
  }, 
  "responseMeta": { 
    "code": 200, 
    "error": "", 
    "success": true 
  } 
}

Various Errors in Device Activation

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=ACTIVATE

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP
89105212033100003483,2305test123,Bob’s Device 1,TestDeviceGroup
89105212033100003484,,Bob’s Device 2,TestDeviceGroup
89105212033100003485,Cluster123,Bob’s Device 3,TestDeviceGroup
89105212033100003486,Cluster123,Bob’s Device 4,TestDeviceGroup
90102315010999901130,Cluster123,Bob’s Device 5,TestDeviceGroup
90105212033100000244,Cluster123,Bob’s Device 6,TestDeviceGroup

Errors in the above ICCID Inputs:

89105212033100003486 – Invalid/Not existing ICCID Record
90105212033100000244 – ICCID not into the provisioned state

Successful API Response:

89105212033100003485 – This is a valid ICCID

Response:

{ 
  "data": { 
    "failed_devices": [   
      { 
        "action": "DEVICE_ACTIVATION", 
        "iccids": [ 
          "89105212033100003486" 
        ], 
        "reason": "No IMSI records found for the given ICCIDs" 
      }, 
      { 
        "action": "DEVICE_ACTIVATION", 
        "iccids": [ 
          "90105212033100000244" 
        ], 
        "reason": "ICCID status needs to be 'Provisioned' for activation, following ICCIDs are not provisioned" 
      } 
    ], 
    "successful_devices": [ 
      { 
        "action": "DEVICE_ACTIVATION", 
        "iccids": [ 
          "89105212033100003485" 
        ] 
      } 
    ] 
      { 
        "action": "DEVICE_NAME_UPDATE", 
        "iccids": [          
          "89105212033100003485"         
    ]       
     }
    ] 
  }, 
  "responseMeta": { 
    "code": 200, 
    "error": "", 
    "success": true 
  } 
}

Errors in Device Group Assignment

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=DG_ASSIGN

Input CSV File:

ICCID,CLUSTER_NAME,DEVICE_NAME
89105212033100003497,Cluster123,,
89105212033100003498,Cluster123,,
89105212033100003500,Cluster123,,
89105212033100000193,Cluster123,,TestDeviceGroup

Errors in above ICCID Inputs:

89105212033100000193 – Devices already assigned to a Device Group
89105212033100003498 – Invalid Device Group
89105212033100003500 – Invalid/Not existing ICCID Record

Successful API Response:

89105212033100003497 – Valid Record

Response:

{ 
  "data": { 
    "failed_devices": [ 
      { 
        "action": "DEVICE_GROUP_ASSIGNMENT", 
        "iccids": [ 
          "89105212033100000193" 
        ], 
        "reason": "Devices already are assigned to a Device Group, please reassign them first" 
      }, 
      { 
        "action": "DEVICE_GROUP_ASSIGNMENT", 
        "iccids": [ 
          "89105212033100003500" 
        ], 
        "reason": "No IMSI records found for the given ICCIDs" 
      }, 
      { 
        "action": "DEVICE_GROUP_ASSIGNMENT", 
        "iccids": [ 
          "89105212033100003498" 
        ], 
        "reason": "Device group: new1 doesn't exist" 
      } 
    ], 
    "successful_devices": [ 
      { 
        "action": "DEVICE_GROUP_ASSIGNMENT", 
        "iccids": [ 
          "89105212033100003497" 
        ] 
      } 
    ] 
  }, 
  "responseMeta": { 
    "code": 200, 
    "error": "", 
    "success": true 
  } 
}

Additional Examples with SIM lock parameters

Example 1

ICCID,CLUSTERNAME,DEVICENAME,DEVICEGROUPNAME,SIMLOCKSTATUS,SIMLOCKPOLICY,SIMLOCKEXPECTEDIMEI 
89105212033100003500,,DeviceTest1,,Enabled,ONATTACH, 89105212033100003501,,DeviceTest2,,Disabled,, 89105212033100003502,,,,Enabled,IMEIMAPPING,123456789012345

SIM lock will be enabled on attach for 89105212033100003500. Even though SIMLOCKEXPECTEDIMEI is not relevant for ONATTACH policy, it still has to be provided for the CSV record as at least one of the optional SIM lock parameters were specified.
SIM lock will be disabled for 89105212033100003501. Even though SIMLOCKPOLICY and SIMLOCKEXPECTEDIMEI are not relevant when SIM lock is disabled, they still have to be provided for the CSV record as at least one of the optional sim lock parameters were specified.

SIM lock will be enabled with IMEI mapping for 89105212033100003502. All the SIM lock fields are provided here. ClusterName and DeviceName are omitted from the record and are specified with ,,

Example 2

ICCID,ClusterName,DeviceName,DeviceGroupName 89105212033100003500,,DeviceTest1, 89105212033100003501,,,DeviceGroup1

The optional SIM lock fields are not provided for these two records. If the op_code provided for this is ACTIVATE, then devices will be activated with SIM lock disabled.

Sim Lock Related CSV Validations

As part of the response of the CSV file API request, a list of failed and successful devices are reported. Based on the optional sim lock fields that are added, there are a few more validations and errors that might be seen for a device. These errors are listed below:

InvalidSimLockEntries:

Sample Response

Reason: Invalid Sim Lock Params, all sim lock fields must be specified and valid. SimLockStatus must be Enabled/Disabled, SimLockPolicy should be IMEIMAPPING/ONATTACH when enabled, SimLockExpectedIMEI should be empty for IMEIMAPPING and must be specified for ONATTACH
Resolution: Fix the record based on the instructions provided in the message

SimLockUnsupportedEntries:

Sample Response

Reason: Sim Lock configurations are not supported when GROUPBASEDDEVICEACTIVATION and NEWIPDOMAINWORKFLOW flags are disabled. SimLockStatus should be Disabled or left empty
Resolution: Fix the record based on the instructions provided in the message

DEFAULTLOCKONACTIVATION

Sample Response

Reason: DEFAULTLOCKONACTIVATION flag is enabled for the customer which means that all the devices are required to be locked during activation.
Resolution: Fix the record by enabling sim lock and adding in a policy for the record

Celona Network Monitoring API: How To

Celona SIM Lifecycle Management

Restrict API access to specific Device Groups

eSIM Activation Guide