The heart of ADNOS is overlaying numbers. Given a destination number, you can use the system to produce a different number which, when dialled, will be routed to the same place. This number will be kept by the system for a time, typically 30 days, at which point if it has not been dialled the number will be returned to the pool for use elsewhere. As a result, you should never rely on the system returning the same overlaying number for the same destination, but instead make a fresh request every time you need an overlay. This will also reset the expiry time, so popular numbers will almost never expire.
The simplest overlay requires only three pieces of information:
Note, depending on the types of number involved, calls may generate revenue or incur a cost. Typically your account will be restricted in what types of number you can use until specific charges and rebates have been negotiated. Please contact firstname.lastname@example.org for more information.
The reference string can be a source of confusion. This string should be used to identify the circumstances under which you would like to receive the same overlaying number again in the future. For an online business directory this might be an identifier for the business to be called; in an advertising campaign it could be the combination of keywords that have brought this specific user to your website. It is possible always to obtain the same overlaying number, or to get a different number for every request. Deciding when to provide the same reference string is a key point in the integration of ADNOS into your application.
Note, if you provide a different reference string for every request you will very quickly use a lot of numbers. This will usually result in you receiving a "pool depleted" error after you have used up your allowance, on the other hand, if you never change the reference string, every overlay request will return the same number regardless of destination. This could result in a poor experience for your users as the number you have provided is redirected to satisfy a later request.
Suppose we want to overlay the number 0800 1234567 with a geographic number, as this is a test we may as well use a reference string of 'test'. We will use the "numberOverlay" method and we need to send three pieces of information to the server: