In order to configure/control PRODUCT, please use URL: http://ip-of-server-where-PRODUCT-is-installed/api.php

Contents

Learn about OTA campaigns – YateOTA Requests, YateOTA Responses and YateOTA Errors

Request: query_campaigns

Retrieve aggregated information about OTA campaigns.

Requests

Responses

Errors

Requests

This request has multiple formats in which it can be sent:

{
    "request": "query_campaigns",
    "node": "ota",
    "params": {}
}
{
    "request": "query_campaigns",
    "node": "ota",
    "params": {
        "limit": "Number of campaigns to return",
        "offset": "The starting point to return campaigns"
    }
}
{
    "request": "query_campaigns",
    "node": "ota",
    "params": {
        "campaign_id": "Return a single campaign by specifying the campaign_id"
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "Name of the campaign",
            "type": "Campaign Type",
            "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.",
            "canceled": "Flag that show if campaigned is canceled or not. Bool format."
        }
    ]
}
{
    "code": 0,
    "campaigns": [
        {
            "campaign": "Name of the campaign",
            "type": "Campaign Type",
            "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.",
            "canceled": "Flag that show if campaigned is canceled or not. Bool format."
        }
    ]
}
{
    "code": 0,
    "campaign": [
        {
            "campaign": "Name of the campaign",
            "type": "Campaign Type",
            "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.",
            "canceled": "Flag that show if campaigned is canceled or not. Bool format."
        }
    ]
}

Errors

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

Examples: query_campaigns

Retrieve status for each campaign.

Request

Response

Request

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

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "sched test rfm",
            "type": "rfm",
            "participants": 1,
            "finished": 1,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 0
        },
        {
            "campaign": "Interval Test",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 1
        },
        {
            "campaign": "Test RAM",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1,
            "canceled": 0
        },
        {
            "campaign": "Test RAM 2",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1,
            "canceled": 0
        }
    ]
}

Retrieve status for a limited number of campaigns using parameters limit and offset.

Request

Response

Request

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

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "sched test rfm",
            "type": "rfm",
            "participants": 1,
            "finished": 1,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 0
        },
        {
            "campaign": "Interval Test",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 0,
            "canceled": 1
        },
        {
            "campaign": "Test RAM",
            "type": "ram",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 0,
            "failed": 1,
            "canceled": 0
        }
    ]
}

Retrieve status for a single campaign by specifying campaign_id.

Request

Response

Request

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

Response

{
    "code": 0,
    "campaigns": [
        {
            "campaign": "TEST RFM 03",
            "type": "rfm",
            "participants": 1,
            "finished": 0,
            "pending_build": 0,
            "pending_send": 1,
            "failed": 0,
            "canceled": 0
        }
    ]
}

Request: action_campaign

Modify a RAM/RFM OTA campaign status

Requests

Responses

Errors

Requests

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign. Required.",
        "action": "stop/pause/restart"
    }
}

Responses

{
    "code": 0
}

Errors

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

Examples: action_campaign

Stop a running campaign.

Request

Response

Request

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144,
        "action": "stop"
    }
}

Response

{
    "code": 0
}

Pause a running campaign.

Request

Response

Request

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144,
        "action": "pause"
    }
}

Response

{
    "code": 0
}

Restart a campaign.

Request

Response

Request

{
    "request": "action_campaign",
    "node": "ota",
    "params": {
        "campaign_id": 144,
        "action": "restart"
    }
}

Response

{
    "code": 0
}

Request: query_participants

Retrieve participants for an OTA campaign

Requests

Responses

Errors

Requests

This request has multiple formats in which it can be sent:

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign."
    }
}
{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign.",
        "limit": "Number of participants to return",
        "offset": "The starting point to return participants from a campaign"
    }
}
{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign.",
        "limit": "Number of participants to return",
        "offset": "The starting point to return participants from a campaign",
        "state": "pending_build/pending_send/failed/finished. Return participants from a campaign after state."
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "count": "Number of participants from an OTA campaign."
}
{
    "code": 0,
    "participants": [
        {
            "participant_id": "ID of the participant",
            "imsi": "International Mobile Subscriber Identity",
            "msisdn": "Phone number.",
            "state": "Participant status",
            "participants": "Number of participants defined in campaign.",
            "error": "Error described if status is failed."
        }
    ]
}
{
    "code": 0,
    "participants": [
        {
            "participant_id": "ID of the participant",
            "imsi": "International Mobile Subscriber Identity",
            "msisdn": "Phone number.",
            "state": "Participant status set in request.",
            "participants": "Number of participants defined in campaign.",
            "error": "Error described if status is failed."
        }
    ]
}

Errors

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

Examples: query_participants

Retrieve number of participants set in a campaign.

Request

Response

Request

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": "176"
    }
}

Response

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

Retrieve a limited number of participants set in a campaign using parameters limit and offset.

Request

Response

Request

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": 167,
        "offset": 0,
        "limit": 20
    }
}

Response

{
    "code": 0,
    "participants": [
        {
            "participant_id": 186,
            "imsi": "001010000010991",
            "msisdn": "963888810991",
            "state": "finished",
            "error": null
        }
    ]
}

Retrieve participants set in a campaign by specifying status.

Request

Response

Request

{
    "request": "query_participants",
    "node": "ota",
    "params": {
        "campaign_id": 167,
        "offset": 0,
        "limit": 20,
        "state": "finished"
    }
}

Response

{
    "code": 0,
    "participants": [
        {
            "participant_id": 186,
            "imsi": "001010000010991",
            "msisdn": "963888810991",
            "state": "finished",
            "error": null
        }
    ]
}

Request: action_participant

Change participant status for an OTA campaign

Requests

Responses

Errors

Requests

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "comment__participants": "A combination of below.Either imsi/iccid + optionally campaign_id / partiticipant_id",
        "participant_id": "Id of the participant.",
        "campaign_id": "If retry_build is for iccid/imsi for specific campaign",
        "iccid": "",
        "imsi": "",
        "action": "Required. One of: cancel/hurry/retry/retry_build/rerun. Action is based on participant status."
    }
}

Responses

{
    "code": 0
}

Errors

{
    "code": 402,
    "message": "Missing all parameters."
}
{
    "code": 402,
    "message": "Missing required 'campaign_id' field."
}
{
    "code": 402,
    "message": "Missing required 'action' field."
}
{
    "code": 401,
    "message": "Can't hurry failed SMS. Use retry option."
}

Examples: action_participant

Retry building messages for previously unallocated imsi/iccid. Used when defininng campaign per large imsi/iccid ranges and some sims don't have subscribers yet. This participants will be marked as unallocated and this request can be used to trigger building campaign for then when they first appear online.

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "iccid": "SIM ICCID as it was used when campaign by range was added",
        "action": "retry_build"
    }
}

Rerun older campaigns for imsi/iccid/msisdn. Used in case of esim profile being downloaded again. Before rerunning campaigns ota_counter per sim is reset to initial value. If request is per msisdn is per msisdn, only campaigns that were for than msisdn/current imsi are rerun -- in case user kept his number and moved to sim to esim. Campaigns for older sims should not be run again.

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "iccid": "SIM ICCID as it was used when campaign by range was added",
        "imsi": "",
        "msisdn": "",
        "action": "rerun"
    }
}

Hurry a pending message.

Request

Response

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "participant_id": "Id of the participant.",
        "action": "hurry",
        "comment__action": "Messages that have status failed/waiting_por can not be hurried."
    }
}

Response

{
    "code": 0
}

Retry to send a message.

Request

Response

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "participant_id": "195",
        "action": "retry"
    }
}

Response

{
    "code": 0
}

Cancel sending a message.

Request

Response

Request

{
    "request": "action_participant",
    "node": "ota",
    "params": {
        "participant_id": "195",
        "action": "cancel"
    }
}

Response

{
    "code": 0
}

Request: trace

Trace participants from an OTA campaign.
Parameter campaign_id is mandatory.
One of the following parameters must pe specified: participant_id/msisdn/imsi

Requests

Responses

Errors

Requests

{
    "request": "trace",
    "node": "ota",
    "params": {
        "campaign_id": "Id of the campaign. Mandatory Parameter",
        "participant_id": "Id of the participant. Optional Parameter.",
        "msisdn": "Phone Number.  Optional Parameter",
        "imsi": "IMSI.  Optional Parameter"
    }
}

Responses

{
    "code": 0,
    "trace": {
        "participant": {
            "participant_id": "Id of the participant",
            "campaign_id": "Id of the campaign",
            "imsi": "IMSI",
            "msisdn": "MSISDN",
            "state": "State of the participant",
            "kic": "Key Identifier for ciphering. Used for encryption",
            "kid": "Key Identifier for RC/CC/DS. Used to verify integrity data.",
            "counter": "Counter used for replay detection and sequence integrity.",
            "cla": "Class Byte.",
            "spi": "Security Parameter Indicator.",
            "kic_alg": "Key and algorithm Identifier for ciphering. Algorithm type used for encryption.",
            "kid_alg": "Key and algorithm Identifier for RC/CC/DS. Algorithm type used to  compute RC/CC/DS field to verify integrity data.",
            "tar_ram": "Toolkit Application Reference for RAM.",
            "tar_rfm_sim": "Toolkit Application Reference for RFM SIM",
            "tar_rfm_usim": "Toolkit Application Reference for RFM USIM"
        },
        "messages": [
            {
                "message_id": "Id of the message.",
                "campaign_id": "Id of the campaign",
                "participant_id": "Id of the participant",
                "state": "State of the message",
                "tpdu": "Transport Protocol Data Unit",
                "msisdn": "MSISDN",
                "originator": "Source number",
                "ud": "User Data",
                "operation": "Operation",
                "por": "Proof of Request",
                "por_status": "PoR Decoded",
                "last_error": "Last error occurred.",
                "tries": "Attempts to send message",
                "next_try": "Date and time when the message will be retried.",
                "expires": "Date and time when message will be marked as failed.",
                "submitted": "Date and time when message was sent."
            }
        ]
    }
}

Errors

{
    "code": 402,
    "message": "Please specify imsi/msisdn for trace"
}
{
    "code": 402,
    "message": "Missing required campaign_id/participant_id field"
}

Examples: trace

Trace a participant from a campaign by specifying participant_id.

Request

Response

Request

{
    "request": "trace",
    "node": "ota",
    "params": {
        "campaign_id": "142",
        "participant_id": "161"
    }
}

Response

{
    "code": 0,
    "trace": {
        "participant": {
            "participant_id": 161,
            "campaign_id": 142,
            "imsi": "001010000010991",
            "msisdn": "963888810991",
            "state": "pending_send",
            "kic": "86ADE6DAF787FF199ACB51FFA118F765",
            "kid": "D6490DCB0EC849A66E43A455916D7DC0",
            "counter": "0000000070",
            "cla": "80",
            "spi": "1621",
            "kic_alg": "15",
            "kid_alg": "15",
            "tar_ram": "000000",
            "tar_rfm_sim": "b00010",
            "tar_rfm_usim": "b00001"
        },
        "messages": [
            {
                "message_id": 615,
                "campaign_id": 142,
                "participant_id": 161,
                "state": "pending",
                "tpdu": null,
                "msisdn": "963888810991",
                "originator": "963880099",
                "ud": "02700000601516211515B000106298D8459514F188A229D099FA9D4F5C2E39C29643A96A26867022AF0F8FFB5681A3D96DC109D3175D2D7BE93E335FA12E10BF131FA2230D7B5EB97A3E41C0EF356BF2BAD01A695208F2D32F7FD23098AC291DB85DC2A13C",
                "operation": "rfm",
                "por": null,
                "por_status": null,
                "last_error": null,
                "tries": 3,
                "next_try": "2019-10-15 12:01:51",
                "expires": "2019-10-29 11:01:51",
                "submitted": "2019-10-15 12:01:51"
            }
        ]
    }
}

Request: query_stats

Retrieve statistics from a running node.
More information about this request here

This documentation was generated on 04 May 2026

YateOTA – JSON API for Control & Stats

Request: query_campaigns

Request: action_campaign

Request: query_participants

Request: action_participant

Request: trace

Request: query_stats