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.

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:

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:

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:

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:

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.