Bulk Ringpool API¶

Before using the Bulk RingPool API, submit a case via the Community Case Portal to enable the Bulk RingPool API feature. It is recommended that before you enable the feature on your production platform, testing occurs on a demo or test platform.

Overview¶

The Bulk RingPool API is designed to efficiently handle a high volume of requests per second. A persistent connection is strongly recommended.

The Bulk RingPool API can be enabled on the Network, Advertiser, or Publisher level. Note that once enabled, all new or edited RingPools are served by the Bulk RingPool API and not the RingPool API. Therefore, if the Bulk RingPool API is enabled for your organization, attempting to access a RingPool with the RingPool API results in an error.

Finally, also note that only the custom RingPool type is supported by the Bulk RingPool API.

Example API URL:

POST https://pnapi.invoca.net/api/2013-07-01/bulk.json

Request Body¶

The JSON POST body of the request has a top level key “request” which maps to an array of hashes, where each hash contains a RingPool API URL. The array must contain at least one entry. The requests follow a similar format to the RingPool API, which can be found here.

Each hash in the array must contain a key/value pair with a key of “api_suffix”. The value must be the suffix of the RingPool API URL after /api/<date>.

At least one RingPool parameter must be present in each allocation request, even if the value is an empty string.

Each element may also include a key/value pair with a key of “request_id”. If provided, it is echoed in the response for context. This parameter is optional and does not have to be unique across the hashes.

Individual responses and request IDs are returned in the same order as the requests.

In addition to marketing data parameters, Signal parameters can be included in the api_suffix query string. See the Signals section below for details.

Below is an example of the JSON request body:

{
 "requests":[
  {"api_suffix":"<RING_POOL_ID>/allocate_number.json?ring_pool_key=<RING_POOL_KEY>&m1=autos&m2=ford","request_id":"193C5F"},
  {"api_suffix":"<RING_POOL_ID>/allocate_number.json?ring_pool_key=<RING_POOL_KEY>&m1=antiques","request_id":"58CD4F"},
  {"api_suffix":"<RING_POOL_ID>/allocate_number.json?ring_pool_key=<RING_POOL_KEY>&m1=electronics","request_id":"E3901B"}
 ]
}

Signals¶

The Bulk RingPool API supports passing Signals as part of the attribution data collected at number allocation time. Signals must be pre-configured in your network’s Custom Data Configuration before use.

Signals are passed as query parameters in the api_suffix string, using the same URL parameter syntax as marketing data parameters. The parameter name must match the Signal’s configured name (matching is case-insensitive). Signal values are interpreted as booleans. Any value other than false or 0 (case-insensitive) is treated as true. A value of false or 0 is treated as false.

Below is an example request that passes a Signal named SMS Callback alongside a marketing data parameter:

{
 "requests":[
  {"api_suffix":"<RING_POOL_ID>/allocate_number.json?ring_pool_key=<RING_POOL_KEY>&m1=autos&SMS%20Callback=true","request_id":"193C5F"}
 ]
}

Signals stored in the attribution data are available to Invoca’s IVR routing logic (condition nodes) when the associated call arrives, enabling use cases such as priority routing based on pre-call attribution.

If a Signal parameter is passed but the Signal name is not found at the time of the call (for example, because it was renamed or deleted), the Signal is silently ignored and does not produce an error.

Response Body¶

The response format is in JSON.

Below is an example response (whitespace added for clarity):

{
 "responses":[
  {"request_id":"193C5F","promo_number_formatted":"888-390-6665","promo_number":"8883906665","tracking_url":"http://ringrevenue.com/c/1/14-11-109?us=http%3A%2F%2Fwww2.ringrevenue.com.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8883906665%26PPCPN%3D8883906665"},
  {"request_id":"58CD4F","promo_number_formatted":"877-455-1120","promo_number":"8774551120","tracking_url":"http://ringringrevenue.com/c/1/19-99-210?us=http%3A%2F%2Fwww2.ringrevenue.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8774551120%26PPCPN%3D8774551120"},
  {"request_id":"E3901B","promo_number_formatted":"866-971-5703","promo_number":"8669715703","tracking_url":"http://ringringrevenue.com/c/1/38-240-19?us=http%3A%2F%2Fwww2.ringrevenue.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8669715703%26PPCPN%3D8669715703","overflow":true}
 ]
}

Note the last response above has “overflow”:true. This indicates that the number returned is the overflow number for that RingPool. To simplify the normal case when the number is not overflow, the key-value pair is omitted when the value would be false.

Additionally, Bulk API responses return the total server processing (this does not include transit) time for the request in the header under the key “processing-time”, and is reported in milliseconds.

Errors¶

The Bulk RingPool API clearly identifies errors when a request can not be processed. For example, when the parameters are incorrect, an error response will be returned for that row in the response as shown below:

{
   "responses":[
    {"request_id":"193C5F","promo_number_formatted":"888-390-6665","promo_number":"8883906665","tracking_url":"http://ringrevenue.com/c/1/14-11-109?us=http%3A%2F%2Fwww2.ringrevenue.com.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8883906665%26PPCPN%3D8883906665"},
    {"request_id":"58CD4F","error_class":"InvalidKey","message":"API Key 'A329F4DC002168' is not valid for resource '1'"},
    {"request_id":"E3901B","promo_number_formatted":"866-971-5703","promo_number":"8669715703","tracking_url":"http://ringringrevenue.com/c/1/38-240-19?us=http%3A%2F%2Fwww2.ringrevenue.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8669715703%26PPCPN%3D8669715703"}
  ]
}

As another example, the following exception occurs when attempting to allocate a number with the RingPool API against a RingPool that has been set up to use the Bulk RingPool API:

{
    "errors":
    {
        "invalid_data":"Numbers are automatically allocated by the PNAPI server",
        "class”:”OnlyBulkNumberAllocationAllowed"
    }
}

If a system error occurs, an InternalServiceError will be returned with an integer error handle.

Submit a case via the Community Case Portal to determine the root cause of such an error.