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
