1. User guide
   1. 1 Overview
   2. 2 Getting started
      1. 2.1 Connecting
      2. 2.2 A simple overlay
      3. 2.3 Moving an overlay
      4. 2.4 Canceling an overlay
      5. 2.5 Overlaying multiple numbers
      6. 2.6 What next
   3. 3 A more advanced overlay
      1. 3.1 Call announcements
      2. 3.2 Call recordings
      3. 3.3 Advertisers
      4. 3.4 Expiry options
         1. 3.4.1 Setting an expiry
         2. 3.4.2 Enforcing the expiry
         3. 3.4.3 The called extension
      5. 3.5 Restricting calls
         1. 3.5.1 Who can call
         2. 3.5.2 The length of calls
         3. 3.5.3 The number of calls
   4. 4 Advertisers functions
      1. 4.1 Create an advertiser
      2. 4.2 List advertisers
      3. 4.3 Edit an advertiser
   5. 5 Sound file functions
      1. 5.1 Pre-call anouncements
         1. 5.1.1 Create an announcement
         2. 5.1.2 List announcements
         3. 5.1.3 Edit an announcement
         4. 5.1.4 Delete an announcement
      2. 5.2 Call recordings
         1. 5.2.1 Get recordings
   6. 6 Statistical functions
      1. 6.1 Call statistics
         1. 6.1.1 Raw statistics
         2. 6.1.2 Grouped statistics
      2. 6.2 Overlay statistics
         1. 6.2.1 Count your overlays
         2. 6.2.2 List your overlays
      3. 6.3 Real time reporting
   7. 7 Miscellaneous functions
      1. 7.1 Check values
         1. 7.1.1 List number types
         2. 7.1.2 List number classes
         3. 7.1.3 Check a parameter
      2. 7.2 Check settings
         1. 7.2.1 Check your permissions
         2. 7.2.2 Check your settings
         3. 7.2.3 Check call costs
         4. 7.2.4 Check costs for a call
      3. 7.3 Check previous requests
         1. 7.3.1 Count previous requests
         2. 7.3.2 List previous requests
         3. 7.3.3 View request details
   8. 8 Glossary

3.4.1 Setting an expiry

When you create an overlay it will remain assigned for a period of time even if it is not called. The length of time it stays assigned for depends on your account settings, but the value is usually thirty days. For some implementations the overlay is only required for a few minutes, in this situation the number could usefully be freed up afterwards allowing the same overlay to be used elsewhere and reducing the total amount of overlaying numbers used.

Example

A user is visiting our website, we want to tie a potential call from this user to to other statistics we have collected online. We can acheive this by passing a unique ID as the referene string, but if we do that for every visitor to the website we will quickly use up a large volume of numbers.
If the user does not call within one hour, we are unlikely to receive a call at all so we can set the overlay to expire one hour from now. We do this by providing an expiry parameter in addition to any other information.

• The unix timestamp that the overlay should expire: expiry=1713620559

Note, on its own this parameter just specifies when the number can be re-used if it is not called. Depending on your implementation you may wish to combine it with the enforceExpiry and / or calledExtension parameters.