Ringpools - Invoca

Similar to Promo Numbers, because these are generated by Invoca, the interface is idempotent. By default, RingPools will capture params based on your Marketing Data Dictionary. Learn more about RingPools here.

Property	Type	Value
id	integer (read-only)	The internal Invoca id of the RingPool.
id_from_network	string (required)	Network specific id of the RingPool. Unique within network. Not required when auto-generation is enabled at network level.
name	string	Arbitrary string. Names the RingPool.
object_url	string (read-only)	URL for reaching the RingPool in the UI.
lifetime_seconds	integer	The guaranteed minimum time that the number will be allocated for this RingPool.
max_pool_size	integer	The maximum amount of phone numbers to be allotted at one time. The default value is 2.
preferred	boolean	true or false. Selects this RingPool if the advertiser has multiple RingPools for the campaign and the web integration code does not specify which pool to use.
destination_phone_number	A phone number to be associated with the RingPool.	Only applicable for `POST` & `PUT /ring_pools/<ring_pool_id>` API endpoint. When using Destinations UI or the forward to destination IVR node, this number will be used.
obfuscated_tag_id	string (required if the network is using Tag Destinations and a destination_phone_number is passed in)	Only applicable for `POST` & `PUT /ring_pools/<ring_pool_id>` API endpoint. The Tag that will be associated with the Destination.
fill_immediately	boolean	When true, the ringpool will immediately be filled with phone numbers up to the max_pool_size, if numbers are available. When false, the pool will initially fill at 10% capacity to conserve phone number usage. The ringpool will increase phone numbers based on ringpool autoscaling settings and traffic volume.
delete_detected_phone_number	boolean (Default false)	Only applicable for `DELETE /ring_pools/<ring_pool_id>` API endpoint. When true, it deletes the linked destinations as well. When false, the destinations are kept as is.
allow_overflow	boolean	Determines what should happen if visitor traffic exceeds the pool size. When true, the RingPool will reserve one phone number for “overflow” and apply it to any additional visitors. When false, the destination phone number will not be replaced on the website. This field can be passed with a value of true or false when creating a RingPool. If updating a RingPool, the field may only be provided if the value is the same as when it was created (i.e. no change). If trying to change the value on an update request, the request will fail. If not passed when creating a new RingPool, the RingPool will be created using the default setting of true.
customer_phone_numbers	Array of hashes	Only applicable for `GET /ring_pools/<ring_pool_id>` API endpoint. Returns a list of all Destinations (aka Customer Phone Numbers) along with the respective `obfuscated_tag_id` for the destinations that are linked to the RingPool.
default_customer_phone_number	Hash	Only applicable for `GET /ring_pools/<ring_pool_id>` API endpoint. Returns the default Destination (aka Customer Phone Number) along with the respective `obfuscated_tag_id` for the destination that is linked to the RingPool.
hours_of_operation	hash (optional)	Configures when the destination is available to receive calls. If not provided, the campaign’s hours of operation settings will apply. Requirements: This field is only available for ring pools that have at least one customer phone number (destination) associated with an advertiser campaign. Ring pools without destinations or with destinations linked only to JS tags cannot use this field. “open_24_7”: boolean. When true, the destination is always available. When false, schedules must be provided. “time_zone”: string (required). Rails ActiveSupport timezone name (e.g., “Pacific Time (US & Canada)”, “Eastern Time (US & Canada)”, “Central Time (US & Canada)”, “Mountain Time (US & Canada)”, “Arizona”). “schedules”: array of hashes (required when open_24_7 is false). Each schedule contains: “day_of_week”: string. Day of the week: “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, or “Saturday”. “open_time”: string. Opening time in HH:MM format (15-minute increments, e.g., “09:00”). “close_time”: string. Closing time in HH:MM format (15-minute increments, e.g., “17:00”). Schedules cannot overlap. To remove hours of operation, pass null, empty string, empty array, or empty hash.

Endpoint:

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

NOTE: Creating DestinationsIf a valid phone number is given for destination_phone_number as part of the POST request, a Destination, aka Customer Phone Number, will be generated and associated with the created RingPool.Additionally, if the network is configured to use Tag Destinations, the obfuscated_tag_id for a JsTag must be given as well.

GET /ring_pools

Read all RingPools as an array. Endpoint:

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json

Response Code: 200 Response Body:

[
  {
    "id": "value",
    "id_from_network": "5432",
    "object_url": "https://invoca.net/a_campaigns/ring_pools/11",
    "preferred": true,
    "lifetime_seconds": 1800,
    "name": "value",
    "local_center": { "tn_prefix":"",
                      "zipcode": "90210",
                      "latitude": 30,
                      "longitude": -130 },
    "local_number_preferences": { "search_radius_miles": 20,
                                  "restrict_search_to_state": true,
                                  "allocation_fallback_strategy": "Wait" },
    "max_pool_size": 15,
    "api_key": "value",
    "fill_immediately": false,
    "allow_overflow": true,
    "customer_phone_numbers": [
      {
        "destination_phone_number": "8005551216",
        "js_tag": {
          "obfuscated_tag_id": "0054811245"
        }
      }
    ],
    "default_customer_phone_number": {
      "destination_phone_number": "8005551216",
      "js_tag": {
        "obfuscated_tag_id": "0054811245"
      }
    }
  }
]

GET /ring_pools/<ring_pool_id>

Read a RingPool. Endpoint:

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Response Code: 200 Response Body:

{
  "id": "value",
  "id_from_network": "5432",
  "object_url": "https://invoca.net/a_campaigns/ring_pools/11",
  "preferred": true,
  "lifetime_seconds": 1800,
  "name": "value",
  "local_center": { "tn_prefix":"",
                    "zipcode": "90210",
                    "latitude": 30,
                    "longitude": -130 },
  "local_number_preferences": { "search_radius_miles": 20,
                                "restrict_search_to_state": true,
                                "allocation_fallback_strategy": "Wait" },
  "max_pool_size": 15,
  "api_key": "value",
  "fill_immediately": false,
  "allow_overflow": true,
  "customer_phone_numbers": [
    {
      "destination_phone_number": "8005551216",
      "js_tag": {
        "obfuscated_tag_id": "0054811245"
      }
    }
  ],
  "default_customer_phone_number": {
    "destination_phone_number": "8005551216",
    "js_tag": {
      "obfuscated_tag_id": "0054811245"
    }
  }
}

POST /ring_pools

Create a RingPool. Endpoint:

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json

Format: application/json Request Body:

{
  "id_from_network": "12",
  "local_center": { "tn_prefix":"",
                    "zipcode": "90210",
                    "latitude": 30,
                    "longitude": -130 },
  "local_number_preferences": { "search_radius_miles": 20,
                                "restrict_search_to_state": true,
                                "allocation_fallback_strategy": "Wait" },
  "preferred": true,
  "name": "Invoca Example RingPool",
  "max_pool_size": 15,
  "lifetime_seconds": 1800,
  "fill_immediately": false,
  "allow_overflow": true,
  "destination_phone_number": "888-111-2222"
}

Response Code: 201 Response Body: Same as a GET response, includes all the RingPool properties.

PUT /ring_pools/<ring_pool_id>

Update a RingPool. Endpoint:

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Format: application/json Request Body:

{
  "id_from_network": "12",
  "preferred": true,
  "name": "Invoca Example RingPool Updated",
  "max_pool_size": 15,
  "lifetime_seconds": 1800
}

Response Code: 200 Response Body: Same as a GET response, includes all the RingPool properties.

DELETE /ring_pools/<ring_pool_id>

Delete a RingPool. Endpoint:

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Format: application/json Response Code: 200 Response Body:

{}

Local RingPool API

Local RingPool Creation

The API provides the ability to create RingPools with additional information that specifies them as being ‘Local’ RingPools. These Local RingPools use local numbers that are determined by the parameters passed in by the user of the API. If a local phone number cannot be found the pool fills those slots (max_pool_size) with toll free numbers instead. When you POST with the correct parameters the Local RingPool is created and the allocation of local numbers happens later (approx. 10 minutes). This capability is JSON-only.

POST

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json

Content Type: application/json

Property	Type	Value
id	integer (read-only)	The internal Invoca id of the RingPool.
id_from_network	string (required)	Network specific id of the RingPool. Unique within network. Not required when auto-generation is enabled at network level.
name	string	Arbitrary string. Names the RingPool.
destination_type	string	One of: Advertiser, API
object_url	string (read-only)	URL for reaching the RingPool in the UI.
lifetime_seconds	integer	The guaranteed minimum time that the number will be allocated for this RingPool.
max_pool_size	integer	The maximum amount of phone numbers to be allotted at one time. The default value is 2.
preferred	boolean	true or false. Selects this RingPool if the advertiser has multiple RingPools for the campaign and the web integration code does not specify which pool to use.
fill_immediately	boolean	When true, the ringpool will immediately be filled with phone numbers up to the max_pool_size, if numbers are available. When false, the pool will initially fill at 10% capacity to conserve phone number usage. The ringpool will increase phone numbers based on ringpool autoscaling settings and traffic volume.
local_center	hash	Requires one of the following. Latitude & Longitude required together. A filled field determines the center to start looking for local numbers at. “tn_prefix”: an npa. “zipcode”: a valid zipcode. “latitude”: a valid latitude. “longitude”: a valid longitude.
local_number_preferences	hash	All are optional. “search_radius_miles”: An integer, greater than or equal to 0. Default is 240. Represents the number of miles from the location to search. “restrict_search_to_state”: A boolean. Default is true. Used to restrict search to be within state boundaries. “allocation_fallback_strategy”: “UseTollFree” or “Wait”. Default is “UseTollFree”. If we are unable to fill the RingPool using the location information provided, we will use this parameter to either fill it with TollFree (“UseTollFree”) or continue to wait until more numbers become available.
tn_prefix_whitelist	array of strings	An array of stringified limiters on the boundaries of where to look for local numbers given as npa (ex. [“805”, “212”]).
destination_phone_number	A phone number to be associated with the RingPool.	Only applicable for `POST` & `PUT /ring_pools/<ring_pool_id>` API endpoint. When using Destinations UI or the forward to destination IVR node, this number will be used.
obfuscated_tag_id	string (required if the network is using Tag Destinations and a destination_phone_number is passed in)	Only applicable for `POST` & `PUT /ring_pools/<ring_pool_id>` API endpoint. The Tag that will be associated with the Destination.
allow_overflow	boolean	Determines what should happen if visitor traffic exceeds the pool size. When true, the RingPool will reserve one phone number for “overflow” and apply it to any additional visitors. When false, the destination phone number will not be replaced on the website. If not passed, the RingPool will be created using the default setting of true.
hours_of_operation	hash (optional)	Configures when the destination is available to receive calls. If not provided, the campaign’s hours of operation settings will apply. Requirements: This field is only available for ring pools that have at least one customer phone number (destination) associated with an advertiser campaign. Ring pools without destinations or with destinations linked only to JS tags cannot use this field. “open_24_7”: boolean. When true, the destination is always available. When false, schedules must be provided. “time_zone”: string (required). Rails ActiveSupport timezone name (e.g., “Pacific Time (US & Canada)”, “Eastern Time (US & Canada)”, “Central Time (US & Canada)”, “Mountain Time (US & Canada)”, “Arizona”). “schedules”: array of hashes (required when open_24_7 is false). Each schedule contains: “day_of_week”: string. Day of the week: “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, or “Saturday”. “open_time”: string. Opening time in HH:MM format (15-minute increments). “close_time”: string. Closing time in HH:MM format (15-minute increments). Schedules cannot overlap. To remove hours of operation, pass null, empty string, empty array, or empty hash.

Response Code: 200 Request Body

{
 "id_from_network": "395",
 "preferred": "true",
 "name": "India DNP",
 "max_pool_size": "3",
 "local_center": {"latitude": 45, "longitude": 45},
 "tn_prefix_whitelist": ["455"],
 "destination_phone_number": "888-111-2222",
 "allow_overflow": false,
 "hours_of_operation": {
   "open_24_7": false,
   "time_zone": "Pacific Time (US & Canada)",
   "schedules": [
     {
       "day_of_week": "Monday",
       "open_time": "09:00",
       "close_time": "17:00"
     },
     {
       "day_of_week": "Tuesday",
       "open_time": "09:00",
       "close_time": "17:00"
     },
     {
       "day_of_week": "Wednesday",
       "open_time": "09:00",
       "close_time": "17:00"
     },
     {
       "day_of_week": "Thursday",
       "open_time": "09:00",
       "close_time": "17:00"
     },
     {
       "day_of_week": "Friday",
       "open_time": "09:00",
       "close_time": "17:00"
     }
   ]
 }
}

Response Body Same as a GET response, includes all the RingPool properties.

Error Handling

Forbidden – 403

POST

https://invoca.net/api/@@HOURS_OF_OPERATION_API_VERSION/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json

Content Type: application/json Response Code: 403 Request Body

{
  "id_from_network": "395",
  "preferred": "true",
  "name": "India DNP",
  "max_pool_size": "3",
  "local_center": {"bad_key": ""},
  "tn_prefix_whitelist": ["455"]
}

Response Body

{
  "errors": {
     "class": "RecordInvalid",
     "invalid_data": "Invalid Key in Local Center."
  }
}

​GET /ring_pools

​GET /ring_pools/<ring_pool_id>

​POST /ring_pools

​PUT /ring_pools/<ring_pool_id>

​DELETE /ring_pools/<ring_pool_id>

​Local RingPool API

​Local RingPool Creation

​POST

​Error Handling

​Forbidden – 403

GET /ring_pools

GET /ring_pools/<ring_pool_id>

POST /ring_pools

PUT /ring_pools/<ring_pool_id>

DELETE /ring_pools/<ring_pool_id>

Local RingPool API

Local RingPool Creation

POST

Error Handling

Forbidden – 403