# 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.

```json
{
  "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"
  }
}
```

### Attributes

| 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](#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:

```json
"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" }
]
```

## List all Number Pools

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

> Returns an array of wrapped Number Pool objects:

```json
[
  {
    "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"
    }
  }
]
```

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

### HTTP Request

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

### Query parameters

| 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

| Status | Description                           |
| ------ | ------------------------------------- |
| 200    | Array of wrapped Number Pool objects. |

## Get a specific Number Pool

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

> Returns a single wrapped Number Pool:

```json
{
  "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"
  }
}
```

### HTTP Request

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

### Path parameters

| Parameter | Type    | Description                                     |
| --------- | ------- | ----------------------------------------------- |
| id        | integer | Retreaver's internal ID for the Number Pool.    |

### Responses

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

## Create a Number Pool

```shell
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
          }
        }'
```

> Returns the newly created, wrapped Number Pool:

```json
{
  "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"
  }
}
```

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

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

### Body parameters

| 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:

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

Create with Google Analytics enabled:

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

Local pool assigned to an affiliate:

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

### Responses

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

## Update a Number Pool

```shell
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}}'
```

> Returns the updated, wrapped Number Pool:

```json
{
  "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"
  }
}
```

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

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

### Body parameters

Accepts the same fields as [Create a Number Pool](#create-a-number-pool), all optional.

### Example requests

Increase the pool size:

```json
{ "number_pool": { "max_pool_size": 1000 } }
```

Set the visitor retention buffer:

```json
{ "number_pool": { "buffer_seconds": 300 } }
```

Enable Google Analytics:

```json
{ "number_pool": { "google_analytics": true } }
```

### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Number Pool updated.  |

## Delete a Number Pool

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

Deletes the given Number Pool.

> [!WARNING]
> This also deletes all Numbers associated with the Number Pool.

### HTTP Request

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

### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Number Pool deleted.  |