> ## Documentation Index
> Fetch the complete documentation index at: https://guides.affiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage pools — create, get, update, delete

> CRUD operations for pools: create a named set of networks and merchants, retrieve it by ID, update its contents, or delete it.

## List pools

Returns all pools for the authenticated team.

**`GET /v1/pools`**

### Query parameters

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Results per page.
</ParamField>

***

## Create pool

Creates a new pool.

**`POST /v1/pools`**

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body parameters

<ParamField body="name" type="string" required>
  Pool name. Min 2, max 255 characters. Must be unique per team.
</ParamField>

<ParamField body="description" type="string">
  Optional description of the pool.
</ParamField>

<ParamField body="url" type="string">
  Optional URL associated with the pool.
</ParamField>

<ParamField body="is_default" type="boolean">
  Whether this pool is the team's default pool.
</ParamField>

<ParamField body="networks" type="string[]">
  Array of network IDs to include in the pool.
</ParamField>

<ParamField body="merchants" type="string[]">
  Array of merchant IDs to add to the pool — bare ID, no `nmer_`/`mer_` prefix (see note below).
</ParamField>

### Example request

```json theme={null}
{
  "name": "My Product Pool",
  "description": "Pool for outdoor products",
  "url": "https://example.com",
  "is_default": false,
  "networks": ["NETWORK_ID_1", "NETWORK_ID_2"],
  "merchants": ["MERCHANT_ID_1", "MERCHANT_ID_2"]
}
```

### Response `201`

```json theme={null}
{
  "id": "01JPSEEDP1ATA11P0010000100",
  "team_id": 1,
  "user_id": 1,
  "name": "My Product Pool",
  "description": "Pool for outdoor products",
  "url": "https://example.com",
  "is_default": false,
  "status": "active",
  "networks": [
    { "id": "NETWORK_ID_1", "name": "ShareASale" }
  ],
  "included_merchants": [
    { "id": "MERCHANT_ID_1", "name": "Acme Co" }
  ],
  "excluded_merchants": []
}
```

<Note>
  `included_merchants[].id` / `excluded_merchants[].id` are the merchant's **bare** ID — no
  `nmer_`/`mer_` prefix, unlike the IDs `GET /v1/merchants` returns. To look one up directly,
  prepend `nmer_` (e.g. `id: "01khfmw45fc139x9w8fsb133yb"` →
  `GET /v1/merchants/nmer_01khfmw45fc139x9w8fsb133yb?extended=1`). The `merchants` request
  parameter (here, in Update, and in [Pool merchants](/api-reference/pools/pool-merchants)) takes
  this same bare form.
</Note>

***

## Get pool

Retrieves a single pool by its ULID.

**`GET /v1/pools/{id}`**

Returns the same shape as the create response.

***

## Update pool

Updates an existing pool. `networks` and `merchants` are diffed — IDs in the request replace the current set (new IDs are added, missing IDs are removed).

**`PUT /v1/pools/{id}`**

### Body parameters

Same shape as create pool.

```json theme={null}
{
  "name": "Updated Pool Name",
  "description": "Updated description",
  "url": "https://example.com",
  "is_default": true,
  "networks": ["NETWORK_ID_1"],
  "merchants": ["MERCHANT_ID_1"]
}
```

Returns `200` with the same shape as the create response — `included_merchants` /
`excluded_merchants`, not `merchants`.

***

## Delete pool

Deletes a pool by its ULID.

**`DELETE /v1/pools/{id}`**