YateOTA – JSON API for OTA Campaigns

Instructions on how to use the JSON API to control OTA Campaigns. Requests, responses, and errors for retrieving Over-the-air campaigns.

Request: get_campaign

Retrieve OTA campaigns
This request has multiple formats in which it can be sent:
{
    "request": "get_campaign",
    "node": "ota",
    "params": {}
}
{ "request": "get_campaign", "node": "ota", "params": { "limit": "Number of campaigns to return", "offset": "The starting point to return campaigns" } }
{ "request": "get_campaign", "node": "ota", "params": { "campaign_id": "Return a single campaign by specifying the campaign_id" } }
{ "request": "get_campaign", "node": "ota", "params": { "key. One of below": "val", "id": "Campaign id. Returns aggregated info similar to other responses", "campaign": "String. Return aggregated info for campaigns whose name matches this.", "state": "String. Return aggregated info for campaign in stacific state: active/started/finished/..", "msisdn": "String. Return aggregated list of campaign / participant state for campaigns for provided msisdn." } }
Examples: get_campaign
Retrieve the number of campaigns.
{
    "request": "get_campaign",
    "node": "ota",
    "params": {}
}
Retrieve a limited number of campaigns by specifying limit and offset.
{
    "request": "get_campaign",
    "node": "ota",
    "params": {
        "limit": 3,
        "offset": 0
    }
}
Retrieve all information for a single campaign by specifying campaign_id.
{
    "request": "get_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 147
    }
}

Request: add_campaign

Add a new RAM/RFM OTA campaign
This request has multiple formats in which it can be sent:
{
    "request": "add_campaign",
    "node": "ota",
    "params": {
        "campaign": "String. Required. Campaign name",
        "description": "Campaign Description",
        "start_time": "Date and time when campaign starts. Timestamp format.",
        "msisdn": "List of MSISDN(s)",
        "type": "rfm",
        "tar_type": "sim/usim/isim. Type of Toolkit Application Reference.",
        "apdus": "List of APDU(s)"
    }
}
{ "request": "add_campaign", "node": "ota", "params": { "campaign": "String. Required. Campaign name", "description": "Campaign Description", "start_time": "Date and time when campaign starts. Timestamp format.", "msisdn": "List of MSISDN(s)", "type": "rfm", "tar_type": "sim/usim/isim. Type of Toolkit Application Reference.", "commands": { "profile": "String. Optional. Name of the profile to use. If not set, default profile will be used", "app": "String. Required. RFM application to update: gsm/telecom/usim", "batch": [ { "addr": "String or Array if case file in located in directory", "values": "String or Object. If string, it contains the new value for the field. If object with \"old\" and \"new\" keys, then generated UDs will try to encode only the different between the two values." } ] } } }
{ "request": "add_campaign", "node": "ota", "params": { "campaign": "String. Required. Campaign name", "description": "String. Campaign Description", "start_time": "Optional. Date and time when campaign starts. Timestamp format.", "msisdn": "Array. Required. List of MSISDN(s)", "type": "rfm", "tar_type": "sim/usim/isim. Type of Toolkit Application Reference.", "commands": { "profile": "String. Optional. Name of the profile to use. If not set, default profile will be used", "app": "String. Required. RFM application to update: gsm/telecom/usim", "refresh": "Boolean. Default false. Apply a SIM refresh after executing updates.", "restart": "Boolean. Default false. Apply a SIM reset after executing updates.", "updates": { "String. Short EF Name.": "String (for simple EFs) / Object (to specify different attributes in that ef) / Array (Used to set the records if is a linear EF.)." } } } }
{ "request": "add_campaign", "node": "ota", "params": { "campaign": "String. Required. Campaign name", "description": "String. Campaign Description", "start_time": "Optional. Date and time when campaign starts. Timestamp format.", "msisdn": "Array. Required. List of MSISDN(s)", "type": "rfm", "tar_type": "sim/usim/isim. Type of Toolkit Application Reference.", "commands": { "profile": "String. Optional. Name of the profile to use. If not set, default profile will be used", "app": "String. Required. RFM application to update: gsm/telecom/usim", "reads": [ { "ef_name": "String. Required. Short name of the EF.", "df_name": "String. Optional. Short name of the parent DF.", "records": "Array. Optional. Specify which records to read from a linear EF." } ] } } }
{ "request": "add_campaign", "node": "ota", "params": { "campaign": "String. Required. Campaign name", "description": "Campaign Description", "start_time": "Date and time when campaign starts. Timestamp format.", "msisdn": "List of MSISDN(s)", "type": "ram", "operation": "load/install/delete/load_install/delete_load_install.RAM operation used to manage SIM applets.", "non_volatile_data_size": "Used to check if there is space on the SIM before loading an applet. Decimal value(0 - 65535), default is 0.", "volatile_data_size": "Used to check if there is space on the SIM before loading an applet. Decimal value(0 - 65535), default is 0.", "module_aid": "AID of the Executable module previously loaded. Mandatory for install operation.", "instance_aid": "AID of the instance that will be selected. Mandatory for install operation.", "aid": "Applet ID. Used for delete operation to remove applet.", "delete_related_objects": "true/false. If true will delete all the related modules/instances to the specified AID. Format: bool. Default true.", "toolkit_parameters": "sim/uicc or empty string. Used to install a STK/USAT applet.", "access_domain": "Access Domain used to install a STK applet. Size: 1 byte. Format: hex. Default value: FF.", "priority_level": "Priority Level. Size 1 byte. Format hex. Default value: 01.", "max_timers": "Maximum Timers. Size 1 byte. Decimal value (0 - 255). Default value: 0", "max_menu_entry_text": "Maximum Menu Entry Text. Size 1 byte. Decimal value (0 - 255). Default value: 16.", "max_menu_entries": "Maximum Menu Entries. Size 1 byte. Decimal value (0 - 255). Default value: 1.", "multi_tar": "Assign one more more TARs to an applet by separating them with ','.", "max_nr_services": "Maximum Number of Services. Size 1 byte. Decimal Value (0 - 255). Default value: 0.", "uicc_access_app": "UICC Access Application. Format Hex.", "uicc_admin_access_app": "UICC Administrative Access Application. Format Hex.", "app_parameters": "Application Parameters", "applet": "Content of .CAP file base64 encoded.", "applet_name": "Name of the applet" } }
Examples: add_campaign
Create a RFM campaign by specifying APDUs.
{
    "request": "add_campaign",
    "node": "ota",
    "params": {
        "campaign": "RFM UPDATE 1",
        "description": "RFM UPDATE 1",
        "start_time": "1571129995",
        "msisdn": [
            "963888810991"
        ],
        "type": "rfm",
        "tar_type": "sim",
        "apdus": [
            "00A40004023F00",
            "00A40004027F20",
            "00A40004026F46",
            "00D60000110053504E2054657374204C69766975FFFF",
            "00A40004026F7B",
            "00D600000C22F60122F65122F60222F652"
        ]
    }
}
Create a RFM campaign by specifying the batch values to generate APDUs.
{
    "request": "add_campaign",
    "node": "ota",
    "params": {
        "campaign": "RFM UPDATE 2",
        "description": "Add another PLMN",
        "start_time": "1570615620",
        "msisdn": [
            "963888810991"
        ],
        "type": "rfm",
        "tar_type": "sim",
        "commands": {
            "app": "gsm",
            "batch": [
                {
                    "addr": "6F30",
                    "values": {
                        "old": "22F610",
                        "new": "22F61022F601"
                    }
                }
            ]
        }
    }
}
Create a RFM campaign by specifying updates in human readable format.
{
    "request": "add_campaign",
    "node": "ota",
    "params": {
        "campaign": "update_gsm_files",
        "description": "Update GSM files and execute REFRESH command.",
        "start_time": "1570615620",
        "msisdn": [
            "963888810991"
        ],
        "type": "rfm",
        "tar_type": "sim",
        "commands": {
            "app": "gsm",
            "refresh": true,
            "updates": {
                "imsi": "001010940235981",
                "smsp": {
                    "sca": "+147258360"
                },
                "fplmn": "",
                "loci": {
                    "tmsi": ""
                },
                "ad": {
                    "mnc_length": 2
                }
            }
        }
    }
}
Create a RFM campaign to read multiple EFs
{
    "request": "add_campaign",
    "node": "ota",
    "params": {
        "campaign": "read_usim_files",
        "description": "Read IMSI, SMSP (1st record) and SPN from profile Altecom.",
        "start_time": "1570615620",
        "msisdn": [
            "963888810991"
        ],
        "type": "rfm",
        "tar_type": "usim",
        "commands": {
            "app": "usim",
            "profile": "Altecom",
            "reads": [
                {
                    "ef_name": "imsi"
                },
                {
                    "ef_name": "smsp",
                    "records": [
                        1
                    ]
                },
                {
                    "ef_name": "spn"
                }
            ]
        }
    }
}
Create a RAM campaign that loads and installs a SIM toolkit applet.
{
    "request": "add_campaign",
    "node": "ota",
    "params": {
        "campaign": "LOAD+INSTALL HelloSTK",
        "description": "Load and install HelloSTK.",
        "start_time": "1571067480",
        "msisdn": [
            "96388881005"
        ],
        "type": "ram",
        "operation": "load_install",
        "module_aid": "D07002CA44900101",
        "instance_aid": "D07002CA44900101",
        "non_volatile_data_size": "0",
        "volatile_data_size": "0",
        "toolkit_parameters": "sim",
        "access_domain": "ff",
        "priority_level": "01",
        "max_timers": "0",
        "max_menu_entry_text": "16",
        "max_menu_entries": "1",
        "multi_tar": "",
        "app_parameters": "",
        "applet": "MDEwMDExZGVjYWZmZWQwMTAyMDQwMDAxMDdkMDcwMDJjYTQ0OTAwMTAyMDAxZjAwMTEwMDFmMDAwYzAwMWUwMDQyMDAxODAwNmQwMDMyMDAxNzAwMDAwMGE5MDAwNDAwMDIwMDIyMDIwMTAwMDQwMDFlMDIwMDAxMDdhMDAwMDAwMDYyMDEwMTA2MDIxMGEwMDAwMDAwMDkwMDAzZmZmZmZmZmY4OTEwNzEwMDAyMDMwMDBjMDEwOGQwNzAwMmNhNDQ5MDAxMDEwMDIwMDYwMDE4NDM4MDAzMDFmZjAwMDcwMjAwMDAwMDJmMDAzOTgwMDIwMDgxMDEwMTA4ODEwMDAwMDcwMDZkMDAwOTExMTg4YzAwMDQ4ZDAwMDEyYzE4MTk3YjAwMDIwMzdiMDAwMjkyMTAyNDAzMDMwMzhiMDAwMzg4MDA3YTAyMzE4ZjAwMDUzZDhjMDAwNjJlMWI4YjAwMDc3YTAxMjAxODhiMDAwODYwMDM3YTdhMDIyMjhkMDAwOTJkMWQxMDA3NmIxMDFhOGIwMDBhMzIxZmFlMDA2YjA2MTg4YzAwMGI3YTA2MTE4ZDAwMGMyYzE5MDMwNzdiMDAwZDAzN2IwMDBkOTI4YjAwMGUxOThiMDAwZjNiN2EwODAwMzIwMDA0MDAwMjAwMDIwMzAwMTg1NzY1NmM2MzZmNmQ2NTIwNzQ2ZjIwNTQ2ZjZmNzI0MzYxNmQ3MDIwMzIzMDMxMzIwMzAwMGE0ODY1NmM2YzZmMmMyMDUzNTQ0YjAwMDAwMDAwMDUwMDQyMDAxMDAyMDAwMDAwMDY4MTA5MDAwNTAwMDAwMjAzODEwOTBiMDY4MDAzMDAwMTAwMDAwMDA2MDAwMDAxMDM4MDAzMDEwMzgwMDMwMzA2ODEwODAwMDM4MTA4MGMwNjAwMDA1MzA2ODEwYTAwMDUwMDAwMDAwMzgxMGExMzAzODEwYTE2MDkwMDE3MDAwMjFlMmQwMDExMDUwMzA2MDQwOTA4MDQwNTA3MDkwYTBhMDYwNzA0MDQwNA==",
        "applet_name": "HelloSTK.cap"
    }
}
Create a RAM campaign that deletes an applet and all related objects to it.
{
    "request": "add_campaign",
    "node": "ota",
    "params": {
        "campaign": "Delete HelloSTK",
        "description": "Delete HelloSTK.",
        "start_time": "1571067480",
        "msisdn": [
            "96388881005"
        ],
        "type": "ram",
        "operation": "delete",
        "aid": "D07002CA449001",
        "delete_related_objects": true
    }
}

Request: edit_campaign

Edit a RAM/RFM OTA campaign
This request has multiple formats in which it can be sent:
{
    "request": "edit_campaign",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign. Required.",
        "campaign": "Campaign name",
        "description": "Campaign Description",
        "start_time": "Date and time when campaign starts. Timestamp format.",
        "state": "State of the campaign",
        "comment__state": "Depending on state, only some fields can be modified. When state=active all fields can be modified. When status is different than 'active' only campaign name and description can be modified.",
        "msisdn": "List of MSISDN(s)",
        "type": "rfm",
        "tar_type": "sim/usim/isim. Type of Toolkit Application Reference.",
        "apdus": "List of APDU(s)"
    }
}
{ "request": "edit_campaign", "node": "ota", "params": { "campaign_id": "Id of the campaign. Required.", "campaign": "Campaign name", "description": "Campaign Description", "start_time": "Date and time when campaign starts. Timestamp format.", "state": "State of the campaign", "comment__state": "Depending on state, only some fields can be modified. When state=active all fields can be modified. When status is different than 'active' only campaign name and description can be modified.", "msisdn": "List of MSISDN(s)", "type": "ram", "operation": "load/install/delete/load_install/delete_load_install.RAM operation used to manage SIM applets.", "non_volatile_data_size": "Used to check if there is space on the SIM before loading an applet. Decimal value(0 - 65535), default is 0.", "volatile_data_size": "Used to check if there is space on the SIM before loading an applet. Decimal value(0 - 65535), default is 0.", "module_aid": "AID of the Executable module previously loaded. Mandatory for install operation.", "instance_aid": "AID of the instance that will be selected. Mandatory for install operation.", "aid": "Applet ID. Used for delete operation to remove applet.", "delete_related_objects": "true/false. If true will delete all the related modules/instances to the specified AID. Format: bool. Default true.", "toolkit_parameters": "sim/uicc or empty string. Used to install a STK/USAT applet.", "access_domain": "Access Domain used to install a STK applet. Size: 1 byte. Format: hex. Default value: FF.", "priority_level": "Priority Level. Size 1 byte. Format hex. Default value: 01.", "max_timers": "Maximum Timers. Size 1 byte. Decimal value (0 - 255). Default value: 0", "max_menu_entry_text": "Maximum Menu Entry Text. Size 1 byte. Decimal value (0 - 255). Default value: 16.", "max_menu_entries": "Maximum Menu Entries. Size 1 byte. Decimal value (0 - 255). Default value: 1.", "multi_tar": "Assign one more more TARs to an applet by separating them with ','.", "max_nr_services": "Maximum Number of Services. Size 1 byte. Decimal Value (0 - 255). Default value: 0.", "uicc_access_app": "UICC Access Application. Format Hex.", "uicc_admin_access_app": "UICC Administrative Access Application. Format Hex.", "app_parameters": "Application Parameters", "applet": "Content of .CAP file base64 encoded.", "applet_name": "Name of the applet" } }
Examples: edit_campaign
Updates a campaign description.
{
    "request": "edit_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 137,
        "description": "This is a RFM test campaign in date 15/Oct/2019."
    }
}

Request: del_campaign

Deletes a RAM/RFM OTA campaign
{
    "request": "del_campaign",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign. Required."
    }
}
Examples: del_campaign
Delete a campaign by specifying campaign_id.
{
    "request": "del_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144
    }
}

Request: add_range

Add participants to an OTA campaign
This request has multiple formats in which it can be sent:
{
    "request": "add_range",
    "node": "ota",
    "params": {
        "campaign_id": "25",
        "imsi": [
            "IMSI1",
            "IMSI2",
            "IMSI3",
            "..."
        ],
        "msisdn": [
            "MSISDN1",
            "MSISDN2",
            "MSISDN3",
            "..."
        ]
    }
}
{ "request": "add_range", "node": "ota", "params": { "campaign_id": "Id of the campaign.", "imsi": [ { "start": "Start IMSI", "end": "END IMSI" }, { "start": "Start IMSI2", "end": "END IMSI2" } ], "msisdn": [ { "start": "Start MSISDN", "end": "END MSISDN" }, { "start": "Start MSISDN2", "end": "END MSISDN2" } ] } }
Examples: add_range
Add new participants to a campaign that has not started yet.
{
    "request": "add_range",
    "node": "ota",
    "params": {
        "campaign_id": "178",
        "msisdn": [
            "96388881001"
        ]
    }
}
Add new participants by specifying an interval to a campaign that has not started yet .
{
    "request": "add_range",
    "node": "ota",
    "params": {
        "campaign_id": "178",
        "msisdn": {
            "start": "96388881001",
            "end": "96388881005"
        }
    }
}

Request: del_range

Remove participants from an OTA campaign
This request has multiple formats in which it can be sent:
{
    "request": "del_range",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign.",
        "imsi": [
            "IMSI1",
            "IMSI2",
            "IMSI3",
            "..."
        ],
        "msisdn": [
            "MSISDN1",
            "MSISDN2",
            "MSISDN3",
            "..."
        ]
    }
}
{ "request": "del_range", "node": "ota", "params": { "campaign_id": "25", "imsi": [ { "start": "Start IMSI", "end": "END IMSI" }, { "start": "Start IMSI2", "end": "END IMSI2" } ], "msisdn": [ { "start": "Start MSISDN", "end": "END MSISDN" }, { "start": "Start MSISDN2", "end": "END MSISDN2" } ] } }
Examples: del_range
Remove participants from a campaign.
{
    "request": "del_range",
    "node": "ota",
    "params": {
        "campaign_id": "27",
        "msisdn": [
            "96388881001"
        ]
    }
}
Remove participants from a campaign by specifying an interval.
{
    "request": "del_range",
    "node": "ota",
    "params": {
        "campaign_id": "27",
        "msisdn": {
            "start": "96388881002",
            "end": "96388881004"
        }
    }
}
This documentation was generated on 23 September 2023