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

API Integration

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
deactivate deactivate Two Step Process
suspend suspend Two Step Process
reactivate reactivate 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 mandatory IMEI number of the handset
geo_nos mandatory The landline number to assign to the sim
subname mandatory Subscriber name
subadress 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>


Deactivate

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


Reactivate

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 reactivate
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_calling] 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
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_calling] 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
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>
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 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.

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 (only returned by checkstatus)
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 atleast 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
63201 Invalid Landline number
63202 No Landline assigned to iccid
63203 Another number is already assigned to this iccid
63204 Landline already in use

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