RingPools

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.

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.

When using Destinations UI or the forward to destination IVR node, this number will be used.

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.

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.

Endpoint:

https://invoca.net/api/2019-05-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Examples

Read all RingPools as an array.

Endpoint:

https://invoca.net/api/2019-05-01/<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_to_state": true,
                                  "allocation_fallback_strategy": "Wait" },
    "max_pool_size": 15,
    "api_key": "value",
    "allow_overflow": true
  }
]

Examples

Read a RingPool

Endpoint:

https://invoca.net/api/2019-05-01/<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_to_state": true,
                                "allocation_fallback_strategy": "Wait" },
  "max_pool_size": 15,
  "api_key": "value",
  "destination_phone_number": "888-111-2222",
  "allow_overflow": true
}

Examples

Create a RingPool

Endpoint:

https://invoca.net/api/2019-05-01/<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_to_state": true,
                                "allocation_fallback_strategy": "Wait" },
  "preferred": true,
  "name": "Invoca Example RingPool",
  "max_pool_size": 15,
  "lifetime_seconds": 1800,
  "destination_phone_number": "888-111-2222",
  "allow_overflow": true
}

Response Code: 201

Response Body:

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

Examples

Update a RingPool

Endpoint:

https://invoca.net/api/2019-05-01/<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.

Examples

Delete a RingPool

Endpoint:

https://invoca.net/api/2019-05-01/<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/2019-05-01/<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 (Required)

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

preferred

boolean

true or false. Selects this RingPool if the advertiser has multiple RingPools for the campaign and the web integration code does not specifiy 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_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”])

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.

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
}

Response Body

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

Error Handling

Forbidden – 403:

POST

https://invoca.net/api/2019-05-01/<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."
  }
}