SIM admin API

Configuring USIMs

Each action has a corresponding command that should be used with the USIM gateway.

Action Command Information
activate activate Two step process
terminate terminate Two step process
suspend suspend Two step process
unsuspend unsuspend Two step process
add service add service Two step process
remove service remove service Two step process
Change ICCID changeiccid Two step process
Change MSISDN changemsisdn Two step process
Blacklist handset blacklist Two step process
Unblacklist handset unblacklist Two step process
Query ICCID queryiccid One step process
Check status checkstatus One step process. Does not perform an action on the sim but is used to query the state of a previous request

In order to configure a USIM using the gateway, you will need to send a command to the following address:

https://mvno.aql.com/mobile/mvno-management.api.php

The gateway accepts both HTTP GET and POST.

One-step process:
The final state of the request is known immediately in the response.
Two-step process:
Due to the complex nature of some of the commands, the final state cannot be determined in real time. It is recommended that you wait at least 30 minutes before issuing the first checkstatus command. These commands must therefore operate in a two-step process:

1. you must issue one of the commands and obtain a request id

2. you should periodically call the ‘checkstatus’ command to determine if your request was successful or if it failed.

Activate

This must always be the first action that is ever performed on a SIM.
You can use this to check whether the inbound data was sent to your virtual mobile number.

To provision a new SIM, you should submit a request to the gateway using the following HTTP variables.

Note: The following services are always enabled by default on all ICCIDs:

• LTE data

If you would like to disable these services, call the remove service command after this ICCID has been successfully activated.

For an explanation of the services, please see the services section at the end of the document.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes activate
iccid Yes ICCID of the SIM
imei No IMEI number of the handset
msisdn No The telephone number assigned to the SIM
subtitle No Subscriber title (Mr, Dr etc)
subforename Yes Subscriber forename
subsurname Yes Subscriber surname
subaddress Yes Subscriber address line 1
subaddress2 No Subscriber address line 2
subaddress3 No Subscriber address line 3
subpostcode Yes Subscriber postcode
subcity No Subscriber city
subcontactno Yes Subscriber contact phone number
subcontactemail No Subscriber contact email
subcompanyname No Subscriber company name
service[int_roaming] No None – should be left blank
service[int_call] No None – should be left blank
service[premium] No None – should be left blank
service[lte] No None – should be left blank
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successfully queued, the following will be returned:

status: 200 id: <request_id>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Terminate

To terminate an existing SIM, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes terminate
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successfully queued, the following will be returned:

status: 200 id: <request_id>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Unsuspend

To reactivate a previously suspended SIM, you should submit a request to the gateway using the following HTTP variables:

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes unsuspend
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successfully queued, the following will be returned:

status: 200 id: <request_id>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Suspend

To suspend a currently active SIM, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes suspend
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successfully queued, the following will be returned:

status: 200 id: <request_id>

If the request failed for any reason, the following will be returned:

status:<error_code>,<error_code>,….,<error_code>

Add service

To add one or more services to a currently active SIM, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes addservice
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM
service[int_roaming] No None – should be left blank
service[int_call] No None – should be left blank
service[premium] No None – should be left blank
service[mo_sms] No None – should be left blank
service[mt_sms] No None – should be left blank
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successfully queued, the following will be returned:

status: 200 id: <request_id>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Remove service

To remove one or more services from a currently active SIM, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes addservice
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM
service[int_roaming] No None – should be left blank
service[int_call] No None – should be left blank
service[premium] No None – should be left blank
service[mo_sms] No None – should be left blank
service[mt_sms] No None – should be left blank
return-mode No return-mode parameter
return-format No return-format parameter

Note on optional:
Although these rows are marked as optional, a minimum of at least one must be provided.

Response

If the request was successfully queued, the following will be returned:

status: 200 id: <request_id>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Change ICCID

To migrate the settings from a previously activated USIM to a new sim, you should submit a request to the gateway using the following HTTP variables. Please note that the old USIM will be terminated permanently in the process.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes changeiccid
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM
newiccid Yes The new ICCID. It must be unactivated.
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successful, the following will be returned
(please see the checkstatus command for the list of possible requeststate values):

status: 200

requeststate: <requeststate>

iccid: <iccid>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Change MSISDN

To change the MSISDN assigned to an already active USIM, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes changemsisdn
iccid Yes ICCID of the SIM
newmsisdn Yes The new MSISDN. It must be unactivated.
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successful, the following will be returned
(please see the checkstatus command for the list of possible requeststate values):

status: 200

requeststate: <requeststate>

iccid: <iccid>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Blacklist IMEI

To blacklist an IMEI, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes blacklist
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM.
imei Yes IMEI number of the handset.
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successful, the following will be returned
(please see the checkstatus command for the list of possible requeststate values):

status: 200 requeststate: <requeststate> iccid: <iccid>

If the request failed for any reason, the following will be returned:

status:<error_code>,<error_code>,….,<error_code>

Unblacklist IMEI

To unblacklist an IMEI, you should a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes unblacklist
iccid Yes ICCID of the SIM
msisdn Yes The telephone number assigned to the SIM.
imei Yes IMEI number of the handset.
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successful, the following will be returned
(please see the checkstatus command for the list of possible requeststate values):

status: 200 requeststate: <requeststate> iccid: <iccid>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Query ICCID

To query the current state of the ICCID, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes queryiccid
iccid Yes ICCID of the SIM
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request failed for any reason, the following will be returned:
status: <error_code>,<error_code>,….,<error_code>

If the request was successful, the following will be returned
(please see the checkstatus command for the list of possible requeststate values):
status: 200 requeststate: <requeststate> iccid: <iccid>

If the ICCID state is ‘active’ or ‘suspended’, the following additional data will also be returned:

msisdn:<msisdn number of sim>
int_roaming: <1 or 0>
int_call: <1 or 0>
premium: <1 or 0>
mo_voice: <1 or 0>
mt_voice: <1 or 0>
mo_SMS: <1 or 0>
mt_SMS: <1 or 0>
video: <1 or 0>
mms: <1 or 0>
internet: <1 or 0>
imsi: <imsi of the iccid>
pin: <initial pin>
pin2: <initial pin2>puk: <initial puk>
puk2: <initial puk2>

Possible values for ‘iccidstate’

  • unused: The ICCID is currently unused and inactive. It is available for activation.
  • pending: The ICCID is in a transitional state, i.e. it is in the process of becoming activated.
  • terminated: The ICCID has been terminated (either using the deactivate or the changeiccid commnd). This state cannot be undone
  • active: The ICCID is active
  • suspended: The ICCID is currently suspended

Check status

To query the status of a previous request, you should submit a request to the gateway using the following HTTP variables.

Request

Variable Required Content
username Yes Account username
password Yes Account password
command Yes checkstatus
id Yes Request ID returned from the initial request.
return-mode No return-mode parameter
return-format No return-format parameter

Response

If the request was successful, the following will be returned
(please see the checkstatus command for the list of possible requeststate values):

status: 200 requeststate: <requeststate> iccid: <iccid>

If the request failed for any reason, the following will be returned:

status: <error_code>,<error_code>,….,<error_code>

Additionally, if the value for requeststate is ‘success’, the gateway will also return the ICCID and MSISDN:

status: 200 requeststate: <requeststate> iccid: <iccid> msisdn: <msisdn>

Note:
The blacklist and unblacklist commands are independent of the ICCID and so for these two commands, an ICCID and MSISDN will not be returned. Please see examples at the end of the documentation for clarification.

Possible values for ‘requeststate’

  • success: The request was successful. This is a final state.
  • failed: The request failed. This is a final state. The network rejected this request.
  • pending: The request is not yet in a final state. Please wait a short while and re-try the checkstatus request.

Error codes

This table lists all the error codes that the gateway can return:

Error code Description
200 ok
400 Bad request
401 Authentication error
500 Internal system error
600 Invalid command
63001 Invalid ICCID
63003 ICCID not on user’s account
63004 Invalid or missing service parameter
63007 Invalid IMEI
63014 SIM incorrectly configured. Cannot activate. Contact support.
63017 ICCID not active.
63021 Not owner of IMEI.
63022 Poll again later (only returned by checkstatus).
63023 No services specified.
63024 IMEI not blackliated.
63025 Invalid checkstatus ID.
63026 ICCID is in an invalid state.
63027 Network congested – command not executed. We recommend waiting at least five minutes before retrying this request.
63028 Subscriber name is invalid.
63029 Subscriber address is invalid.
63030 Subscriber postcode is invalid.
63031 Subscriber contact number is invalid.
63032 Service(s) not yet supported.
63033 Request rejected by network.
63034 Invalid service for data SIM.
63102 Invalid MSISDN.
63104 Invalid service name.
63105 Cannot set up fax service during activate.
63106 Invalid fax MSISDN.
63108 Porting not enabled.
63109 New port in MSISDN is invalid.
63110 Invalid PAC code.
63111 Invalid port date.
63112 Invalid network operator code.
63113 Invalid service provider code.
63115 MSISDN not paired with ICCID.
63116 ICCID not paired with MSISDN.
63118 MSISDN not active.
63119 Fax already active on ICCID.
63120 MSISDN/ICCID pair not active.
74001 IMSI associated with the ICCID invalid.
74014 SIM not assigned to contact.
74013 ICCID is active.

Examples

Note:
The examples only use the HTTP GET method however you can also use HTTP POST.

Activate example

To activate a USIM with the following data over HTTP GET:

Data Value
iccid 1111111111000000001
username myusername
password mypassword
msisdn 44113000000
subname My Name
subaddress 11 – 15 Hunslet Road, Leeds
subpostcode LS101JQ
subcontactno 441133203040

Request

https://mvno.aql.com/mobile/configure_sim.php?username=myusername&password=mypassword&command=activate&iccid=1111111111000000001&geo_nos=44113000000&subname=My+Name&subaddress=11+–+15+Hunslet+Road%2C+Leeds&subcontactno=441133203040&subpostcode=LS101JQ

Response

If the request was successful, you would get a result similar to:

status: 200

id: 117234

If the request was not successful, you would get a response similar to:

status: 63001

Check status example

To check the status of the above request you would assemble the following request:

Request

https://mvno.aql.com/mobile/configure_sim.php?username=myusername&password=mypassword&command=checkstatus&id=117234

Response

In this situation, examples of possible return values could be

status: 401

or

status: 200
requeststate: success
iccid: 1111111111000000001

or (wait a short period and issue the checkstatus again)

status: 200
equeststate: pending
iccid: 1111111111000000001

or

status: 200
requeststate: failed
iccid: 1111111111000000001

Distributing USIMs

To query or submit a despatch, you will need to call the following URL:

http://gw.aql.com/mobile/despatch_sim.php

For each request, you will need to pass the following variables:

  • username (username of your mobile account)
  • password (password of your mobile account)
  • order_ref (your unique reference for this order)

Followed by the specific command and associated variables.
All commands will return one of the following exit codes or as listed for that command:

  • 0: Successful
  • 1: Authentication error
  • 8: Unrecognised command
  • 9: Undefined error

Despatch a SIM

To despatch a SIM, you will need an order reference which can be used to query the status of the order at a later date. This should be included as part of the following:

  • command=despatch
  • name
  • company
  • address
  • postcode
  • contact_no

Return codes

  • 2 – Missing parameters
  • 3 – Insufficient SIMs on account

Query an order

• command=query

If successful, the following response will be returned in the form:

item:value pairs separated by newlines, e.g.

0: Successful

name:John Smith

company:aql

address:11-15 Hunslet Road,Leeds

postcode:LS10 1JQ

contact_no:441133203040

iccid:1234567890123

status:despatched (or processing if still awaiting despatch, or cancelled if the order was rejected)

Querying stock

• Levels command=check_stock

This will either return a successful response followed by a colon separated list of your SIM batches in the form:

product_code:quantity
i.e. 0: Successful
AQL-123:2031
ABC-456:20000

Return codes

Or, in the event of an error, will return one of the following:

  • 1: Authentication error
  • 9: Unknown error