---
name: natural-list-customers
description: List customers who have delegated payment authority to the authenticated agent. Use when you need to discover which customers you can act on behalf of.
metadata:
  author: Natural
  version: "1.0"
---

# List Customers

Retrieve the list of customers who have delegated payment authority to the authenticated agent.

## Prerequisites

- A valid API key (`sk_*`) is configured

## Workflow

### 1. Retrieve customers

Fetch customers associated with the authenticated API key. Results are paginated — if `hasMore` is `true`, pass the `nextCursor` value as `--cursor` (CLI) or `cursor` (MCP) to fetch the next page. Default page size is 50, max 100.

### 2. Filter for actionable customers

From the results, select only customers where:

- `type` is `"customer"`
- `id` exists and starts with `pty_` (this is the `customerPartyId` used by other skills)

Pending invitations are returned by a separate endpoint and are not actionable customer rows.

### 3. Present results

For each actionable customer, surface:

| Field                                                         | Description                                                              |
| ------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `data[].id`                                                   | The `customerPartyId` (`pty_xxx`) used in payment and transaction lookup |
| `data[].attributes.name`                                      | The customer's display name                                              |
| `data[].attributes.email`                                     | The customer's primary email, when available                             |
| `data[].relationships.delegation.data.attributes.status`      | Customer relationship status                                             |
| `data[].relationships.delegation.data.attributes.permissions` | Delegated permissions                                                    |
| `data[].relationships.agents.data[]`                          | Per-agent access for this customer                                       |

## Error handling

- **Auth error:** API key is missing, invalid, or lacks permission — check credentials
- **Network/server error:** Retry the request

---

## CLI Adapter

Execute the list-customers workflow using the `natural` CLI. All commands should use `--format json` for structured output that agents can parse.

### Command

```bash
natural customers list --format json
```

Response shape:

```json
{
  "data": [
    {
      "type": "customer",
      "id": "pty_xxx",
      "attributes": {
        "name": "John Doe",
        "email": "john@example.com",
        "createdAt": "2026-01-04T15:30:00Z"
      },
      "relationships": {
        "delegation": {
          "data": {
            "type": "delegation",
            "id": "dlg_xxx",
            "attributes": {
              "status": "active",
              "permissions": ["payments.create"],
              "createdAt": "2026-01-04T15:30:00Z"
            }
          }
        },
        "agents": {
          "data": []
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "hasMore": false,
      "nextCursor": null
    }
  }
}
```

Filter: use only resources where `type === "customer"` and `id` starts with `pty_`.

### Exit codes

| Code | Meaning                                    | Action              |
| ---- | ------------------------------------------ | ------------------- |
| 0    | Success                                    | Parse JSON response |
| 1    | Business error                             | Read error message  |
| 3    | Auth error (missing or invalid API key)    | Check credentials   |
| 4    | Network/server error (timeout, rate limit) | Retry               |

### Notes

- Always pass `--format json` — human-formatted output is not designed for agent parsing
- Pass the format flag explicitly for clarity, even when stdout is piped

---

## MCP Adapter

Execute the list-customers workflow using Natural MCP server tools. The MCP server authenticates via Bearer token in the session.

### Tool

Tool: `list_customers`

```json
{
  "limit": 50,
  "cursor": null
}
```

`limit` is optional (default 50, max 100). Pass `cursor` from a previous response's `nextCursor` to paginate.

Same response shape and filtering rules as the CLI adapter. Select resources where `type === "customer"` and `id` starts with `pty_`.

### Error handling

MCP tool errors are returned as tool call failures with an error message. Categorize by the message content:

- Authentication errors: API key issues
- Server errors: retry the request