Number Pools API

Number Pools dynamically assign Numbers to visitors on your website. Use them in lieu of static Numbers when you want to track many different visitor attributes — for example, when an affiliate drives many simultaneous visitors to a landing page and each needs a unique number.

Number Pool object

Every Number Pool response (get, list, create, update) is wrapped in a top-level number_pool key.

{
  "number_pool": {
    "id": 1,
    "numbers_count": 0,
    "type": "Toll-free",
    "country": "US",
    "max_pool_size": 10,
    "buffer_seconds": 0,
    "hide_embedded_access": false,
    "google_analytics": false,
    "afid": "0001",
    "cid": "111",
    "reserve_size": 1,
    "max_lease_seconds": null,
    "created_at": "2026-04-21T16:16:51Z",
    "updated_at": "2026-04-21T16:16:51Z"
  }
}

Swipe horizontally for full code

Attributes

Swipe horizontally to view full table

Attribute	Type	Description
id	integer	Retreaver’s internal ID for this Number Pool.
numbers_count	integer	Count of Numbers currently provisioned in the pool.
type	string	`Toll-free` or `Local`.
country	string	2-letter country code (e.g. `US`, `CA`). Relevant for `Local` pools.
max_pool_size	integer	Maximum Numbers the pool will hold.
buffer_seconds	integer	Seconds a Number retains its visitor assignment after the visitor leaves your site.
hide_embedded_access	boolean	When `true`, hides the embedded affiliate phone number management interface.
google_analytics	boolean	Whether the Google Analytics integration is enabled. Incompatible with affiliate-assigned pools.
afid	string/null	Affiliate AFID this pool belongs to, if any.
cid	string/null	Campaign CID this pool belongs to.
reserve_size	integer	Numbers pre-provisioned and held in reserve for instant assignment.
max_lease_seconds	integer/null	Maximum lease duration a Number may be assigned to a visitor.
google_analytics_paths	array/null	Google Analytics webhook paths. Present only when `google_analytics` is `true`. See GA Paths.
created_at	string	ISO-8601 timestamp of pool creation.
updated_at	string	ISO-8601 timestamp of the last update.

GA Paths

When google_analytics is enabled, google_analytics_paths lists webhook paths for your Google Analytics integration:

"google_analytics_paths": [
  { "name": "Network timer (always)",  "path": "/callpixels/8ddc04aa-0020-45eb-89df-ed45b8ed43a7" },
  { "name": "Network timer (connect)", "path": "/callpixels/18135f62-00ff-4818-941d-d88b6a93f27d" }
]

Swipe horizontally for full code

List all Number Pools

curl "https://api.retreaver.com/number_pools.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Returns an array of wrapped Number Pool objects:

[
  {
    "number_pool": {
      "id": 1,
      "numbers_count": 0,
      "type": "Toll-free",
      "country": "US",
      "max_pool_size": 10,
      "buffer_seconds": 0,
      "hide_embedded_access": false,
      "google_analytics": false,
      "afid": "0001",
      "cid": "111",
      "reserve_size": 1,
      "object_key": "8ddc04aa-0020-45eb-89df-ed45b8ed43a7",
      "max_lease_seconds": null,
      "created_at": "2026-04-21T16:16:51Z",
      "updated_at": "2026-04-21T16:16:51Z"
    }
  }
]

Swipe horizontally for full code

Returns all Number Pools for the authenticated company. Use cid or afid to restrict results to a specific Campaign or Affiliate.

HTTP Request

curl "https://api.retreaver.com/number_pools.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Query parameters

Swipe horizontally to view full table

Parameter	Type	Description
cid	string	Restrict results to Number Pools belonging to the given Campaign ID.
afid	string	Restrict results to Number Pools belonging to the given Affiliate ID.
page	integer	Page of results to return. Defaults to `1`.
per_page	integer	Results per page. Defaults to `25`, maximum `100`.

Responses

Swipe horizontally to view full table

Status	Description
200	Array of wrapped Number Pool objects.

Get a specific Number Pool

curl "https://api.retreaver.com/number_pools/1.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Returns a single wrapped Number Pool:

{
  "number_pool": {
    "id": 1,
    "numbers_count": 0,
    "type": "Toll-free",
    "country": "US",
    "max_pool_size": 10,
    "buffer_seconds": 0,
    "hide_embedded_access": false,
    "google_analytics": false,
    "afid": "0001",
    "cid": "111",
    "reserve_size": 1,
    "object_key": "8ddc04aa-0020-45eb-89df-ed45b8ed43a7",
    "max_lease_seconds": null,
    "created_at": "2026-04-21T16:16:51Z",
    "updated_at": "2026-04-21T16:16:51Z"
  }
}

Swipe horizontally for full code

HTTP Request

curl "https://api.retreaver.com/number_pools/{id}.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Path parameters

Swipe horizontally to view full table

Parameter	Type	Description
id	integer	Retreaver’s internal ID for the Number Pool.

Responses

Swipe horizontally to view full table

Status	Description
200	Number Pool found.
404	No Number Pool with the given ID.

Create a Number Pool

curl -s \
    -X POST \
    "https://api.retreaver.com/number_pools.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json" \
    -d '{
          "number_pool": {
            "cid": "111",
            "max_pool_size": 100,
            "hide_embedded_access": true,
            "google_analytics": true
          }
        }'

Swipe horizontally for full code

Returns the newly created, wrapped Number Pool:

{
  "number_pool": {
    "id": 49,
    "numbers_count": 0,
    "type": "Toll-free",
    "country": "US",
    "max_pool_size": 100,
    "buffer_seconds": 0,
    "hide_embedded_access": true,
    "google_analytics": true,
    "afid": null,
    "cid": "111",
    "reserve_size": 1,
    "object_key": "8ddc04aa-0020-45eb-89df-ed45b8ed43a7",
    "max_lease_seconds": null,
    "google_analytics_paths": [
      { "name": "Network timer (always)",  "path": "/callpixels/8ddc04aa-0020-45eb-89df-ed45b8ed43a7" },
      { "name": "Network timer (connect)", "path": "/callpixels/18135f62-00ff-4818-941d-d88b6a93f27d" }
    ],
    "created_at": "2026-04-21T16:53:52Z",
    "updated_at": "2026-04-21T16:53:52Z"
  }
}

Swipe horizontally for full code

Creates a new Number Pool.

Note

The Campaign referenced by cid must already exist. If assigning an Affiliate via afid, it must also exist before creation.

HTTP Request

curl -X POST "https://api.retreaver.com/number_pools.json?api_key=[api_key]&company_id=1" \
  -H "Content-Type: application/json"

Swipe horizontally for full code

Body parameters

Swipe horizontally to view full table

Parameter	Type	Default	Required	Description
cid	string		required	The Campaign ID this Number Pool belongs to.
afid	string	null		The Affiliate ID this Number Pool belongs to.
type	string	`Toll-free`		`Toll-free` or `Local` — the type of Number to provision.
country	string	`US`		2-letter country code for `Local` pools. Supported: `US CA AT BE DK FI FR GB IE IT NL PL SE`.
max_pool_size	integer	10		Maximum Numbers the pool will hold.
buffer_seconds	integer	0		Seconds a Number retains its visitor assignment after the visitor leaves.
hide_embedded_access	boolean	false		When `true`, hides the embedded affiliate phone number management interface.
google_analytics	boolean	false		Enables the Google Analytics integration. Incompatible with affiliate-assigned pools.
reserve_size	integer	1		Numbers to pre-provision and hold in reserve for instant assignment.

Example requests

Minimal create — cid and pool size:

{ "number_pool": { "cid": "111", "max_pool_size": 100 } }

Swipe horizontally for full code

Create with Google Analytics enabled:

{
  "number_pool": {
    "cid": "111",
    "max_pool_size": 100,
    "hide_embedded_access": true,
    "google_analytics": true
  }
}

Swipe horizontally for full code

Local pool assigned to an affiliate:

{
  "number_pool": {
    "cid": "111",
    "afid": "0001",
    "type": "Local",
    "country": "CA",
    "max_pool_size": 25,
    "buffer_seconds": 300,
    "reserve_size": 5
  }
}

Swipe horizontally for full code

Responses

Swipe horizontally to view full table

Status	Description
200	Number Pool created.
500	Validation failed. Response body: `{ "number_pool": { "errors": { ... } } }`.

Update a Number Pool

curl -s \
    -X PUT \
    "https://api.retreaver.com/number_pools/49.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json" \
    -d '{"number_pool":{"max_pool_size":1000}}'

Swipe horizontally for full code

Returns the updated, wrapped Number Pool:

{
  "number_pool": {
    "id": 49,
    "numbers_count": 0,
    "type": "Toll-free",
    "country": "US",
    "max_pool_size": 1000,
    "buffer_seconds": 0,
    "hide_embedded_access": true,
    "google_analytics": true,
    "afid": null,
    "cid": "111",
    "reserve_size": 1,
    "object_key": "8ddc04aa-0020-45eb-89df-ed45b8ed43a7",
    "max_lease_seconds": null,
    "google_analytics_paths": [
      { "name": "Network timer (always)",  "path": "/callpixels/8ddc04aa-0020-45eb-89df-ed45b8ed43a7" },
      { "name": "Network timer (connect)", "path": "/callpixels/18135f62-00ff-4818-941d-d88b6a93f27d" }
    ],
    "created_at": "2026-04-21T16:53:52Z",
    "updated_at": "2026-04-21T18:53:52Z"
  }
}

Swipe horizontally for full code

Updates the Number Pool with any attributes passed in. Only the provided fields are changed.

Warning

Changing type or country after Numbers have already been provisioned will not reprovision existing Numbers — only newly acquired Numbers reflect the change.

HTTP Request

curl -X PUT "https://api.retreaver.com/number_pools/{id}.json?api_key=[api_key]&company_id=1" \
  -H "Content-Type: application/json"

Swipe horizontally for full code

Body parameters

Accepts the same fields as Create a Number Pool, all optional.

Example requests

Increase the pool size:

{ "number_pool": { "max_pool_size": 1000 } }

Swipe horizontally for full code

Set the visitor retention buffer:

{ "number_pool": { "buffer_seconds": 300 } }

Swipe horizontally for full code

Enable Google Analytics:

{ "number_pool": { "google_analytics": true } }

Swipe horizontally for full code

Responses

Swipe horizontally to view full table

Status	Description
200	Number Pool updated.

Delete a Number Pool

curl -X DELETE "https://api.retreaver.com/number_pools/49.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Deletes the given Number Pool.

Warning

This also deletes all Numbers associated with the Number Pool.

HTTP Request

curl -X DELETE "https://api.retreaver.com/number_pools/{id}.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Responses

Swipe horizontally to view full table

Status	Description
200	Number Pool deleted.