# RevCent MCP Guide: `GetCustomers`

Brief AI/MCP-focused guide for retrieving a bounded operational list of RevCent Customers.

---

## Operation Summary

Operation:

```text
GetCustomers
```

Purpose:

```text
Return a bounded list of previously created Customers.
```

Use `GetCustomers` for narrow operational retrieval over a known date range and small page/limit.

Do not use it for reporting or analytics.

---

## Related Links

| Guide | Link |
|---|---|
| Customer Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomer.md` |
| GetCustomer | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomer.md` |
| SearchCustomers | `https://revcent.com/documentation/markdown/mcp/operation/SearchCustomers.md` |
| Customer Group Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomerGroup.md` |
| Customer Card Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomerCard.md` |
| Sale Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` |
| Subscription Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscription.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetCustomers` only for bounded operational retrieval.

Good uses:

- show recent Customers in a narrow date window,
- review Customers associated with a specific campaign,
- review Customers in a specific customer group,
- review Customers who purchased a specific product,
- review Customers with a specific status,
- locate a Customer ID before using `GetCustomer`,
- perform an operational support lookup with strict date range, page, and limit.

Do not use this operation for reporting or analytics.

---

## Input Schema

Required fields:

| Field | Type | Description |
|---|---:|---|
| `date_start` | integer | Date range start as a Unix timestamp in seconds. |
| `date_end` | integer | Date range end as a Unix timestamp in seconds. |
| `limit` | integer | Number of records to return. Range 1 to 25. Default 25. |
| `page` | integer | Pagination page. |

Optional filters:

| Field | Purpose |
|---|---|
| `campaign_filter` | Filter by one or more Campaign IDs. |
| `customer_group_filter` | Filter by one or more Customer Group IDs. |
| `product_filter` | Filter by one or more Products a customer has purchased. |
| `status_filter` | Filter based on customer status. |
| `metadata_filter` | Filter by one or more metadata name/value pairs. |

Example:

```json
{
  "date_start": 1761955200,
  "date_end": 1764547200,
  "limit": 25,
  "page": 1,
  "status_filter": ["Enabled"]
}
```

---

## Output Summary

`GetCustomers` can return:

| Field | Meaning |
|---|---|
| `current_count` | Current number of items in this response. |
| `current_page` | Current page. |
| `total_count` | Total number of matching items for the operational query. |
| `total_pages` | Total pages for the operational query. |
| `results` | Array of Customer objects. |

Customer result objects can include identity, contact, address, status, campaign, card summaries, customer groups, lifetime value summaries, notes, products purchased, metadata, and related record IDs.

---

## Customer-Facing AI Verification Warning

`GetCustomers` may return sensitive customer records across multiple customers.

If this operation is used inside a customer-facing AI flow, such as an AI Voice Agent, chatbot, customer portal assistant, SMS assistant, or other public AI method, AI/MCP should verify that the visitor is actually related to the returned Customer record before providing information or taking action.

Recommended rule:

```text
Do not provide Customer details to a public-facing visitor based only on visitor-provided filters or lookup input.
```

Even if the visitor provides a name, email, date range, phone number, internal ID, product reference, or other lookup detail, that alone should not be treated as authorization.

Safe flow:

```text
Visitor provides lookup/filter input
    ↓
AI uses GetCustomers for a narrow operational lookup
    ↓
AI identifies likely Customer record(s)
    ↓
AI uses GetCustomer for the specific selected Customer
    ↓
AI verifies the visitor against a secondary value from the retrieved record
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Use a secondary value from the retrieved Customer record, such as customer email, phone, or another record-backed value.


---

## Critical Reporting Rule

These Customer lookup/search operations are **not** reporting tools.

Do not use this operation for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- document property searches,
- customer count reports,
- customer lifetime value reports,
- segmentation reports,
- churn/retention reports,
- acquisition reports,
- campaign/shop/product/customer analytics.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If AI/MCP intended to use this operation for reporting, metrics, aggregation, or data mining and then realizes BigQueryRunQuery is the correct operation, it does not need to tell the user about the correction.

It should simply use BigQueryRunQuery instead.
```



---

## Built-In Usage Warning

`GetCustomers` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve bounded recent Customers | `GetCustomers` |
| Retrieve one known Customer | `GetCustomer` |
| Search for a Customer by term | `SearchCustomers` |
| Count Customers | `BigQueryRunQuery` |
| Segment Customers | `BigQueryRunQuery` |
| Calculate customer lifetime value reports | `BigQueryRunQuery` |
| Report customer acquisition/retention/churn | `BigQueryRunQuery` |
| Analyze customers by campaign/product/status/group | `BigQueryRunQuery` |

---

## Example: Correct Operational Use

```text
User: Show recent enabled Customers in this campaign over the last 7 days.
```

Correct:

```text
Use GetCustomers with campaign_filter, status_filter, date_start, date_end, limit, and page.
```

---

## Example: Incorrect Reporting Use

```text
User: How many customers purchased product X last month by campaign?
```

Incorrect:

```text
Loop through GetCustomers pages and calculate manually.
```

Correct:

```text
Use BigQueryRunQuery.
```

AI/MCP should simply run `BigQueryRunQuery` and not explain that it almost used `GetCustomers`.

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` within schema limits.
4. Use `GetCustomer` for detail review after selecting a Customer.
5. Do not loop through pages to build metrics.
6. Do not use this operation for reporting or data mining.
7. Treat customer data as sensitive.
8. Verify customer identity before sharing Customer details in customer-facing AI flows.
9. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetCustomers` only for bounded operational retrieval of Customers.

In customer-facing AI flows, verify the visitor is related to the returned Customer record using a secondary value from the retrieved record, such as customer email, before providing details or taking action.

Never use it for reporting, metrics, aggregation, counting, broad analysis, data mining, or bulk export. If the user intent is analytical, silently switch to `BigQueryRunQuery`.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.