YateOTA &#8211; JSON API for OTA Campaigns

Requests

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."
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "count": "Number of OTA campaigns"
}
{
    "code": 0,
    "campaigns": [
        {
            "campaign_id": "ID of the campaign",
            "campaign": "Name of the campaign",
            "start_time": "Date and time when campaign starts. Timestamp format.",
            "state": "Campaign status like started, stopped, finished.",
            "participants": "Number of participants defined in campaign.",
            "finished": "Flag that shows if campaigned was finished or not. Bool format.",
            "pending_build": "Flag that shows if SMS construction has started. Bool format.",
            "pending_send": "Flag that shows if the SMS has started to be sent to the participants. Bool format.",
            "failed": "Flag that show if campaigned failed or not. Bool format."
        }
    ]
}
{
    "code": 0,
    "campaign": [
        {
            "campaign_id": "ID of the campaign",
            "campaign": "Name of the campaign",
            "start_time": "Date and time when campaign starts. Timestamp format.",
            "description": "Description of campaign",
            "type": "rfm/ram. Type of OTA Campaign.",
            "apdus": "List of APDU(s)",
            "tar_type": "sim/usim/isim. Type of Toolkit Application Reference.",
            "state": "Campaign status like started, stopped, finished."
        }
    ]
}
{
    "request": "get_campaign",
    "node": "ota",
    "params": {
        "campaign_id": "Return a single campaign by specifying the campaign_id",
        "campaign": "Name of the campaign",
        "start_time": "Date and time when campaign starts. Timestamp format.",
        "campaign_state": "Campaign status like started, stopped, finished.",
        "msisdn": "MSISDN of participant. Same as that set when filtering.",
        "imsi": "IMSI of participant",
        "participant_state": "Status of participant in this campaign.",
        "participant_id": "Participant ID"
    }
}

Errors

{
    "code": 404,
    "message": "Entity not found."
}

Examples: get_campaign

Retrieve the number of campaigns.

Request

{
    "request": "get_campaign",
    "node": "ota",
    "params": {}
}

Response

{
    "code": 0,
    "count": 90
}

Retrieve a limited number of campaigns by specifying limit and offset.

Request

{
    "request": "get_campaign",
    "node": "ota",
    "params": {
        "limit": 3,
        "offset": 0
    }
}

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign_id": 150,
            "campaign": "Delete, Load and INSTALL STK",
            "start_time": 1571142360,
            "state": "finished",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0
        },
        {
            "campaign_id": 149,
            "campaign": "Install STK Applet",
            "start_time": 1571142240,
            "state": "stopped",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1
        },
        {
            "campaign_id": 148,
            "campaign": "Load STK Applet",
            "start_time": 1571142000,
            "state": "finished",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1
        }
    ]
}

Retrieve all information for a single campaign by specifying campaign_id.

Request

{
    "request": "get_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 147
    }
}

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign_id": 147,
            "campaign": "TEST RFM",
            "type": "rfm",
            "description": "This is a RFM campaign.",
            "start_time": 1571135340,
            "apdus": [
                "00A40004023F00",
                "00A40004027F20",
                "00A40004026F30",
                "00D600030322F601"
            ],
            "tar_type": "sim",
            "state": "finished"
        }
    ]
}

Request: add_campaign

Add a new RAM/RFM OTA campaign

Requests

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"
    }
}

Responses

{
    "code": 0,
    "campaign_id": "ID of the campaign created"
}

Errors

{
    "code": 403,
    "message": "Campaign with this name is already defined."
}
{
    "code": 401,
    "message": "Errors encountered while building APDU(s) in gsm application: 6F30(Invalid value for item 'new'.Next PLMN(s) must contain only numbers: 22FA01.)"
}
{
    "code": 401,
    "message": "Errors encountered while building APDU(s) in gsm application: 6F30(Value must be hexadecimal."
}

Examples: add_campaign

Create a RFM campaign by specifying APDUs.

Request

{
    "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"
        ]
    }
}

Response

{
    "code": 0,
    "campaign_id": 121
}

Create a RFM campaign by specifying the batch values to generate APDUs.

Request

{
    "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"
                    }
                }
            ]
        }
    }
}

Response

{
    "code": 0,
    "campaign_id": 122
}

Create a RFM campaign by specifying updates in human readable format.

Request

{
    "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
                }
            }
        }
    }
}

Response

{
    "code": 0,
    "campaign_id": 123
}

Create a RFM campaign to read multiple EFs

Request

{
    "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"
                }
            ]
        }
    }
}

Response

{
    "code": 0,
    "campaign_id": 124
}

Create a RAM campaign that loads and installs a SIM toolkit applet.

Request

{
    "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"
    }
}

Response

{
    "code": 0,
    "campaign_id": 125
}

Create a RAM campaign that deletes an applet and all related objects to it.

Request

{
    "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
    }
}

Response

{
    "code": 0,
    "campaign_id": 126
}

Request: edit_campaign

Edit a RAM/RFM OTA campaign

Requests

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"
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "campaign_id": "Id of the RFM campaign"
}
{
    "code": 0,
    "campaign_id": "Id of the RAM campaign"
}

Errors

{
    "code": 402,
    "message": "Missing all parameters."
}
{
    "code": 403,
    "message": "Campaign with this name is already defined."
}

Examples: edit_campaign

Updates a campaign description.

Request

{
    "request": "edit_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 137,
        "description": "This is a RFM test campaign in date 15/Oct/2019."
    }
}

Response

{
    "code": 0,
    "campaign_id": 137
}

Request: del_campaign

Deletes a RAM/RFM OTA campaign

Requests

{
    "request": "del_campaign",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign. Required."
    }
}

Responses

{
    "code": 0,
    "campaign_id": "Id of the campaign"
}

Errors

{
    "code": 402,
    "message": "Missing all parameters."
}

Examples: del_campaign

Delete a campaign by specifying campaign_id.

Request

{
    "request": "del_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144
    }
}

Response

{
    "code": 0,
    "campaign_id": 144
}

Request: add_range

Add participants to an OTA campaign

Requests

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"
            }
        ]
    }
}

Responses

{
    "code": 0,
    "count": "Number of participants added."
}

Errors

{
    "code": 402,
    "message": "Missing required 'campaign_id' field."
}
{
    "code": 404,
    "message": "No campaign found."
}

Examples: add_range

Add new participants to a campaign that has not started yet.

Request

{
    "request": "add_range",
    "node": "ota",
    "params": {
        "campaign_id": "178",
        "msisdn": [
            "96388881001"
        ]
    }
}

Response

{
    "code": 0,
    "count": 1
}

Add new participants by specifying an interval to a campaign that has not started yet .

Request

{
    "request": "add_range",
    "node": "ota",
    "params": {
        "campaign_id": "178",
        "msisdn": {
            "start": "96388881001",
            "end": "96388881005"
        }
    }
}

Response

{
    "code": 0,
    "count": 5
}

Request: del_range

Remove participants from an OTA campaign

Requests

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"
            }
        ]
    }
}

Responses

{
    "code": 0,
    "count": "Number of participants removed."
}

Errors

{
    "code": 402,
    "message": "Missing required 'campaign_id' field."
}

Examples: del_range

Remove participants from a campaign.

Request

{
    "request": "del_range",
    "node": "ota",
    "params": {
        "campaign_id": "27",
        "msisdn": [
            "96388881001"
        ]
    }
}

Response

{
    "code": 0,
    "count": 1
}

Remove participants from a campaign by specifying an interval.