Premium Rate Billing & Telephony + Mobile Products & SMS Services
Call us on 08444 150 763
(Outside the UK +44 1493 66 00 66)

API: Simple PINs Service

Our Simple PINs service allows you to manage your own databases of PIN numbers for use on our IVR telephony equipment or through other means.

Our Simple PINs service can be used in multiple scenarios, a common one being where a client has a telephony line and PIN numbers to permit access. But if that PIN number is being shared, the client may lose unquantifiable amounts of revenue.

To solve this, our IVR platform integrates with this PIN service, and with our web services API you can manage the PINs enabling access.

PINs may be added, updated, and deleted in bulk. Each PIN may have a start and expiry period. You may download our records of PIN uses. You may organise your PINs into numbered databases.

For PIN security, each database may be configured to record a security key. This is commonly the CLI of the caller when used to dial our IVR. You may specify per-database the maximum number of different CLIs to allow, preventing the effective sharing of PINs on public forums.

Our API enables you to view and delete the security keys used. So if you find that a customer cannot log in because he has unwittingly used his PIN from too many locations you can remove one or more CLIs and enable his access without needing to contact our own staff.

Definitions

Database
This is a number and allows you to group your PINs. You download your current database with this API.
PIN
This is normally a number but can include characters if you wish. It may be up to 15 characters long. A PIN may exist no more than once per database. You can set a PIN to become active and expire at particular points in time.
Use
When a PIN gets successfully used, the event is logged. You can download this log using this API.
Key
To prevent abuse by sharing of PINs by your customers we can record CLIs or other values alongside each use. We can then allow up to x different values per PIN. You can download the keys used and delete them.

API Calls

Please note that these are samples only. You must replace the uid and token values with those issued to you and displayed in our clients.stealthnet.net web site.

URI: http://api.stealthnet.net/simple-pins/?uid=X&token=Y

Next, add some extra parameters based on the action's requirements:

action
This specifies what you want to do. The table further down this page lists each.
db
This is the database you wish to work on. Defaults to 1. May be any integer up to 9999.
pin
Some calls require a single PIN value. List this as pin=value.
start-pin
Some calls require a PIN range for sequential numbers. List this as start-pin=lowest-value.
end-pin
Some calls require a PIN range for sequential numbers. List this as end-pin=highest-value.
expires-at
This should be a point in time, specified in ISO format YYYY-MM-DD HH:MM:SS (url encoded in your HTTP request), when you want the PIN to become inactive. Uses of the service after this time will not find this PIN
begins-at
This should be a point in time, specified in ISO format YYYY-MM-DD HH:MM:SS (url encoded in your HTTP request), when you want the PIN to become active. Uses of the service before this time will not find this PIN
year
A year, given as YYYY.
month
A month, given as MM.
day
A day, given as DD.
output
Currently we only support csv and txt (tab-separated value) however json will likely follow.
List of actions and meaning
Action valueDescription
download-usesDownloads a log of your PINs being used
download-dbDownloads the currently selected database of PINs
download-dbsDownloads a list of databases you have PINs within
write-pinsEnables you to add or update one or more PINs within the selected database
delete-pinsEnables you to delete one or more PINs from the selected database
download-keysEnables the download of all security keys used in conjunction with your pin database
delete-keyEnables you to delete a key. This is useful if you tested a PIN number and need to delete your own entry

The return code is based on the HTTP Protocol. Dependant on your request you may need to specify which output you wish to read from the body of the response.

download-uses

Each time a successful request is made to check a pin number, a record of that request is stored in our database. This call allows you to download a list of such requests.

Parameters required:

  • db
  • year
  • month
  • day

The body will consist of one record per line in comma or tab delimited format with the following columns:

PINDBDate TimeSecurity value used

If you receive an empty body, there are no records to report.

download-dbs

Obtain a list of databases which contain PIN numbers.

Parameters required: None.

The body will consist of one record per line in comma or tab delimited format with the following columns:

DBNumber of PINs

If you receive an empty body, there are no records to report.

download-db

Obtain a list of PINs within a given database.

Parameters required:

  • db

The body will consist of one record per line in comma or tab delimited format with the following columns:

PINDBExpires Date TimeBegins Date Time

download-keys

This provides a quick method of obtaining the security keys listed against an individual PIN. From here you can easily identify and delete keys, allowing further access as necessary.

Parameters required:

  • db
  • pin

The body will consist of one record per line in comma or tab delimited format with the following columns:

PINDBSecurity KeyDate Time first used

delete-key

Allows you to delete a specific security key held against a particular PIN.

Parameters required:

  • db
  • pin
  • value

The body will be blank. A response code 200 indicates success.

write-pins

This is the primary call when creating new PINs or updating existing ones. You can add/update one, or many thousand PINs. If you are adding or updating more than one PIN they must form a sequential range for example 7000-7500. To add or update a single PIN make the start-pin and end-pin values the same.

Parameters required:

  • db
  • start-pin
  • end-pin

Optional parameters:

  • begins-at - When would you like this PIN to become active? If you do not set this the PIN will be active.
  • expires-at - When would you like this PIN to expire? If you do not set this the PIN will be active.

The body will be blank. A response code 200 indicates success. Note that expired PINs remain within the database, but are simple inactive.

delete-pins

Allows you to remove PINs from your database. As with write-pins, we have a start-pin and and end-pin required. Be careful - we cannot restore deleted PINs. When a PIN is deleted we do not remove their uses or any security keys.

  • db
  • start-pin
  • end-pin

The body will be blank. A response code 200 indicates success. Note that a success will be issued if the SQL query returned success - it does not indicate that matching records were actually found.

HTTP Response Codes
HTTPMeaning
200 OKyour request succeeded and depending on what you did you might get a body full of content
401 UNAUTHORIZEDYou have your credentials wrong
403 FORBIDDENYou are trying to do something we don't allow or have passed a parameter value that is invalid
500 INTERNAL SERVER ERRORSomething went wrong with your request and we stopped processing it, please report these as possible bugs
Footer Image