Ringpools¶

Similar to Promo Numbers, because these are generated by Invoca, the interface is idempotent.

Property	Type	Value
name	string	Arbitrary string. Names the RingPool.
pool_type	string (Required)	One of: Search, SearchKeyword, Custom, CustomWithSearchTracking, ReferralDomain, ReferralDomainWithSearchTracking.
destination_type	string (Required)	one of: Advertiser, API.
destination_url	url	like, https://www.invoca.com.
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.
param1	string	Dynamic number pools have attributes named param1 through param10 for custom use by the user.
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.
test_click_url	string	RingPool tracking link.
sample_api_url	string	RingPool API endpoint.
is_first_preference	boolean	Designates the preferred RingPool to be used for general traffic.

Endpoint:

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

GET

/ring_pools

Get all RingPools

Examples

Read all RingPools as an array

Endpoint:

https://invoca.net/api/2016-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",
  "pool_type": "value",
  "is_first_preference": true,
  "destination_url": "",
  "preferred": true,
  "sample_api_url": "value",
  "destination_type": "value",
  "lifetime_seconds": 1800,
  "name": "value",
  "param1": "",
  "param2": "",
  "param3": "",
  "param4": "",
  "param5": "",
  "param6": "",
  "param7": "",
  "param8": "",
  "param9": "",
  "param10": "",
  "max_pool_size": 15,
  "tracking_url": "value",
  "test_click_url": "value",
  "api_key": "value"
}

GET

/ring_pools/<ring_pool_id>

Get a RingPool

Examples

Read a RingPool

Endpoint:

https://invoca.net/api/2016-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",
  "pool_type": "value",
  "is_first_preference": true,
  "destination_url": "",
  "preferred": true,
  "sample_api_url": "value",
  "destination_type": "value",
  "lifetime_seconds": 1800,
  "name": "value",
  "param1": "",
  "param2": "",
  "param3": "",
  "param4": "",
  "param5": "",
  "param6": "",
  "param7": "",
  "param8": "",
  "param9": "",
  "param10": "",
  "max_pool_size": 15,
  "tracking_url": "value",
  "test_click_url": "value",
  "api_key": "value"
}

POST

/ring_pools/<ring_pool_id>

Create a RingPool

Examples

Create a RingPool

Endpoint:

https://invoca.net/api/2016-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:

{
  "param1": "q",
  "param2": "test",
  "param3": "param3",
  "param4": "param4",
  "param5": "param5",
  "param6": "param6",
  "param7": "param7",
  "param8": "param8",
  "param9": "param9",
  "param10": "param10",
  "pool_type": "SearchKeyword",
  "api_key": "1234567890",
  "preferred": true,
  "name": "Invoca Example RingPool",
  "destination_url": "https://www.invoca.com",
  "max_pool_size": 15,
  "tracking_url": "https://www.invoca.com",
  "destination_type": "Advertiser",
  "lifetime_seconds": 1800
}

Response Code: 201

Response Body:

{
}

PUT

/ring_pools/<ring_pool_id>

Update a RingPool

Examples

Update a RingPool

Endpoint:

https://invoca.net/api/2016-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:

{
  "param1": "updated",
  "param2": "test",
  "param3": "param3",
  "param4": "param4",
  "param5": "param5",
  "param6": "param6",
  "param7": "param7",
  "param8": "param8",
  "param9": "param9",
  "param10": "param10",
  "pool_type": "SearchKeyword",
  "api_key": "1234567890",
  "preferred": true,
  "name": "Invoca Example RingPool Updated",
  "destination_url": "https://www.invoca.com",
  "max_pool_size": 15,
  "tracking_url": "https://www.invoca.com",
  "destination_type": "Advertiser",
  "lifetime_seconds": 1800
}

Response Code: 200

Response Body:

{
}

DELETE

/ring_pools/<ring_pool_id>

Delete a RingPool

Examples

Delete a RingPool

Endpoint:

https://invoca.net/api/2016-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/2016-05-01/<network_id>/advertiser/<advertiser_id_from_network>/advertiser_campaign/<advertiser_campaign_id_from_network>/ring_pools/<desired_id_from_network>.json

Content Type: application/json

Property	Type	Value
name	string	Arbitrary string. Names the RingPool.
pool_type	string (Required)	One of: Search, SearchKeyword, Custom, CustomWithSearchTracking, ReferralDomain, ReferralDomainWithSearchTracking
destination_type	string (Required)	One of: Advertiser, API
destination_url	url	like, https://www.invoca.com
object_url	string (read-only)	URL for reaching the RingPool in the UI.
affiliate_id	string (optional)	if specified, an affiliate campaign will be the target, o.w. advertiser campaign is the target
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
param1	string	Dynamic number pools have attributes named param1 through param10 for custom use by the user
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.
test_click_url	string	RingPool tracking link.
sample_api_url	string	RingPool API endpoint.
is_first_preference	boolean	Designates the preferred RingPool to be used for general traffic.
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”: can be either npa or npa or npa-nxx “zipcode”: a valid zipcode “latitude”: a valid latitude “longitude”: a valid longitude
tn_prefix_whitelist	array of strings	an array of stringified limiters on the boundaries of where to look for local numbers given as npa or npa nxx pairs (ex. [“805”, “805612”])

Response Code: 200

Request Body

{
 "param1": "gclid",
 "pool_type": "Custom",
 "preferred": "true",
 "name": "India DNP",
 "destination_url": "https://www.invoca.com",
 "tracking_url": "https://www.invoca.com",
 "max_pool_size": "3",
 "destination_type": "Advertiser",
 "local_center": {"latitude": 45, "longitude": 45},
 "tn_prefix_whitelist": ["455"]
}

Response Body

{}

Error Handling¶

Forbidden – 403:

POST¶

https://invoca.net/api/2016-05-01/<network_id>/advertiser/<advertiser_id_from_network>/advertiser_campaign/<advertiser_campaign_id_from_network>/ring_pools/<desired_id_from_network>.json

Content Type: application/json

Response Code: 403

Request Body

{
  "param1": "gclid",
  "pool_type": "Custom",
  "preferred": "true",
  "name": "India DNP",
  "destination_url": "https://www.invoca.com",
  "tracking_url": "https://www.invoca.com",
  "max_pool_size": "3",
  "destination_type": "Advertiser",
  "local_center": {"bad_key": ""},
  "tn_prefix_whitelist": ["455"]
}

Response Body

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