Text us or call us on : 011 33 20 30 40

Account Login





Lost password?
Signup now

Other Services

aql Telecoms

Click here to view aql's range of voice fax and Business Voice over IP telephony solutions.
Click Here...

SIM Admin

service icon

Choosing your geographic number

Prior to activating a sim, the geographic number must first be allocated to your account. Numbers can be allocated via our Numbering API. If you do not have access to this, please contact your account manager.

Configuring USIMs

There are various different actions that can be performed on a USIM which include:

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 addservice Two Step Process
remove service removeservice Two Step Process
assign geographic number assigngeo One Step Process
change geographic number changegeo One 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/configure_sim.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 realtime. 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.

Please note – any values in red italics are literal values and must be provided to the gateway exactly as stated to activate.


Activate

This must always be the first action that is ever performed on a SIM.
To provision a new SIM, you should submit a request to the gateway using the following HTTP variables.

Request


Variable Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory activate
iccid mandatory ICCID of the SIM
imei optional IMEI number of the handset
geo_nos mandatory The landline number to assign to the sim
subname mandatory Subscriber name
subaddress mandatory Subscriber address
subpostcode mandatory Subscriber postcode
subcontactno mandatory Subscriber contact phone number
return-mode optional return-mode parameter
return-format optional return-mode parameter

NB: The red rows indicate services that Three are due to provide in the future but are not yet available. If you try and apply one of these services, the gateway will respond with an error.

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: (view error codes)
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 Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory terminate
iccid mandatory ICCID of the SIM
geo_nos mandatory The landline number to assign to the sim
return-mode optional return-mode parameter
return-format optional return-mode 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: (view error codes)
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 Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory unsuspend
iccid mandatory ICCID of the SIM
geo_nos mandatory The landline number assigned to the SIM
return-mode optional return-mode parameter
return-format optional return-mode 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: (view error codes)
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 Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory suspend
iccid mandatory ICCID of the SIM
geo_nos mandatory The landline number assigned to the SIM
return-mode optional return-mode parameter
return-format optional return-mode 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: (view error codes)
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 Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory addservice
iccid mandatory ICCID of the SIM
geo_nos mandatory The landline number assigned to the SIM
service[int_roaming] optional None – should be left blank
service[int_call] optional None – should be left blank
service[mo_voice] optional None – should be left blank
service[mt_voice] optional None – should be left blank
service[mo_sms] optional None – should be left blank
service[mt_sms] optional None – should be left blank
service[internet] optional None – should be left blank
return-mode optional return-mode parameter
return-format optional return-mode parameter

NB: The red rows indicate services that Three are due to provide in the future but are not yet available. If you try and apply one of these services, the gateway will respond with an error.

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: (view error codes)
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 Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory removeservice
iccid mandatory ICCID of the SIM
geo_nos mandatory The landline number assigned to the SIM
service[int_roaming] optional None – should be left blank
service[int_call] optional None – should be left blank
service[mo_voice] optional None – should be left blank
service[mt_voice] optional None – should be left blank
service[mo_sms] optional None – should be left blank
service[mt_sms] optional None – should be left blank
service[internet] optional None – should be left blank
return-mode optional return-mode parameter
return-format optional return-mode parameter

NB: The red rows indicate services that Three are due to provide in the future but are not yet available. If you try and apply one of these services, the gateway will respond with an error.

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: (view error codes)
status: <error_code>,<error_code>,....,<error_code>


Assign Geographic Number

To assign a geographic number to an already active USIM, you should submit a request to the gateway using the following HTTP variables.


Request


Variable Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory assigngeo
iccid mandatory ICCID of the SIM
geo_nos mandatory The landline number to assign to the SIM
return-mode optional return-mode parameter
return-format optional return-mode parameter

Response


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

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

If the request failed for any reason, the following will be returned: (view error codes)
status: <error_code>,<error_code>,....,<error_code>


Change Geographic Number

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


Request


Variable Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory changegeo
iccid mandatory ICCID of the SIM
geo_nos mandatory The existing geo landline number on the SIM
new_geo_nos mandatory The new landline number to assign to the SIM
return-mode optional return-mode parameter
return-format optional return-mode parameter

Response


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

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

If the request failed for any reason, the following will be returned: (view error codes)
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 Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory queryiccid
iccid mandatory ICCID of the SIM
return-mode optional return-mode parameter
return-format optional return-mode parameter

Response


If the request failed for any reason, the following will be returned: (view error codes)
status: <error_code>,<error_code>,....,<error_code>

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

status: 200
iccid: <iccid>
iccidstate: <iccid_state>

If the iccid state is 'active' or 'suspended', the following additional data will also be returned:
geo_nos: <geo 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 terminate 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 Name Requirement Value
username mandatory Account Username
password mandatory Account Password
command mandatory checkstatus
id mandatory Request id returned from the initial request
return-mode optional return-mode parameter
return-format optional return-mode parameter

Response


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

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

If the request failed for any reason, the following will be returned: (view error codes)
status: <error_code>,<error_code>,....,<error_code>


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.

Value Added Services APIs

The V.A.S. APIs detailed here are for Crisp, Voicemail and Call Recording services provided to fully mediated partners of our MVNO service.


Crisp Service

To enable or disable the crisp service for an active USIM, you should submit a request to the gateway using the following HTTP variables. Requests should be sent to the following URL using HTTP GET or HTTP POST methods:


https://mvno.aql.com/mobile/configure_sim.php

Request


Variable name Requirement Value
username mandatory Account username
password mandatory Account password
command mandatory crisp
iccid mandatory ICCID of SIM
geo_nos mandatory The existing landline number of the SIM
action mandatory Possible values:
enable-new
enable-existing
disable
parent-sms-number optional The SMS number of the parent to be notified.
See notes on 'action' below
crisp-email mandatory The Crisp account identifier is an email address
crisp-password optional The Crisp account password
See notes on 'action' below
return-mode optional return-mode parameter
return-format optional return-mode parameter

Values for 'action'

'enable-new' If the end users does not already have an existing Crisp account, this command will create an account with Crisp and also enable the Crisp service on the SIM.
The 'crisp-password' and 'parent-sms-number' parameters need to be provided for this action.
'enable-existing' If the end user already has a existing Crisp account, this command will enable the Crisp service on the Sim. The Crisp service will be enabled on the account provided by the crisp-email parameter.
'disable' This disables an existing Crisp service from the SIM.

Response


If the request was successfully, the following will be returned:
status: 200
crispstate: <state>
The values for state are either 'enabled' or 'disabled'
If the request failed for any reason, the following will be returned
status: <error_code>,<error_code>,....,<error_code> (view error codes)

Voicemail

Request


To configure voicemail services you should end a command to the following URI using HTTP GET or HTTP POST methods;
https://mvno.aql.com/services/vm.php

Three actions are available; these should be passed to the API in the “command” parameter;

ValueDescription
usernameusername of your mobile account
passwordpassword of your mobile account
geo_noin E164 format (e.g. 441133203040)
command config - used to activate or change configuration of voicemail service
remove - used to deactivate the voicemail service on a number
info - info returns information on current configuration of the voicemail service

The following parameters can be configured on the voicemail service and can be specified as arguments to the config command:

ValueDescription
delaydelay in seconds before the call is sent to voicemail
pina four digit PIN for accessing voicemail externally
emailthe eMail address to send notifications / voicemails to
notifyBoolean (1 or 0) – If 1 will notify email of new voicemail
attachBoolean (1 or 0) – If 1 will attach recording to notification - note that notify must be set to 1 for this to function.

Response


As per all our MVNO APIs If your request is successful the following will be returned:
status: 200

Additionally the “info” command above will return the current value of each of the configurable parameters in the same format e.g.;
status: 200
delay: 30
pin: 1234
email: support@uk.aql.com
notify: 1
attach: 1

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

Notes The voicemail greeting can be personalised at any time by dialling 500 from the active handset.
Although there is a documented PIN for voicemail retrieval when dialling from an external number, the external number to call is not in place at present, but will be added in the near future.


Call Recording

Request


To configure call recording services you should end a command to the following URI using HTTP GET or HTTP POST methods;
https://mvno.aql.com/services/rec.php
Three actions are available; these should be passed to the API in the “command” parameter;

ValueDescription
usernameusername of your mobile account
passwordpassword of your mobile account
geo_noin E164 format (e.g. 441133203040)
command config - used to activate or change configuration of recording service
remove - used to deactivate the recording service on a number
info - returns information on current configuration of the recording service

The following parameters can be configured on the call recording service and can be specified as arguments to the config command:

ValueDescription
activeBoolean (1 or 0) - Set to 1 to enable call recording
ondemandBoolean (1 or 0) - If 1 “on demand” recording is enabled, see below *
emailthe email address to send notifications / recordings to
notifyBoolean (1 or 0) - If 1 will notify email of new recording
attachBoolean (1 or 0) – If 1 will attach a recording to notification - note that notify must be set to 1 for this to function **
  • * “on demand” call recording, when enabled, will not record calls by default, but any call can be recorded by pressing *5 – you can decide to record the call at any time. The entire call will be recorded even if *5 is only keyed shortly before the end of the call.
  • ** at present this is the only way to retrieve the call recordings, so this parameter should always be set to 1.

More methods to retrieve voicemail will be offered in the future.


Response


As per all our MVNO APIs If your request is successful the following will be returned:
status: 200
 Additionally the “info” command above will return the current value of each of the configurable parameters in the same format e.g.;
status: 200
active: 1
email: support@uk.aql.com
ondemand: 0
notify: 1
attach: 1
If the request failed for any reason the following will be returned;
status: <error_code>,<error_code>..


Error Codes

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

Errorcode Description
200 OK
400 Bad request
401 Authentication error
500 Internal system error
600 Invalid Command
63001 Invalid ICCID
63003 ICCID not on users 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
63023 No Services specified
63024 IMEI not blacklisted
63025 Invalid checkstatus id
63026 Iccid is in an invalid state
63027 Network congested – Command not executed. We recommend waiting at least 5 minutes before re-trying 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 a data SIM
63104 Invalid service name
63201 Invalid Landline number
63202 No Landline assigned to iccid
63203 Another number is already assigned to this iccid
63204 Landline already in use
63207 The Crisp action is invalid
63208 The Crisp email address is invalid
63209 The parent SMS number is invalid
63210 The Crisp password is invalid
63211 The Crisp number is not valid
63212 The Crisp service could not disabled
65001 Not owner of number
65002 No Voicemail service present

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
geo_nos 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




checkstatus 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
requeststate: 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

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

  • 1: Authentication Error
  • 9: Unknown Error
©1999-2012 aql ®
Terms & Conditions | Sitemap |Privacy Policy |Security |Contact us |Careers |FAQs