> This page is for Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getmodulate.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getmodulate.dev/_mcp/server.

# Introduction

The **Modulate Partner API** gives ISO partners programmatic access to every dimension of their merchant portfolio — pricing, processor profiles, transactions, statements, residuals, compliance, and AI-powered insights — through a single, consistent REST API.

#### [Get your API key](/partner-api/overview/getting-started/authentication)

Learn how to authenticate and make your first request in minutes.

#### [Quickstart guide](/partner-api/overview/getting-started/quickstart)

Pull live merchant data and pricing in under 5 minutes.

#### [API Reference](/partner-api/api-reference)

Browse all endpoints with live request and response examples.

## What you can build

#### Portfolio dashboards

Display live merchant health, volume trends, and residual summaries directly inside your own platform.

#### Automated pricing tools

Pull current and historical TSYS pricing for any merchant to power competitive analysis or repricing workflows.

#### Statement delivery

List and download merchant statements programmatically — great for automated distribution or archiving.

#### Residual reporting

Access payout summaries, adjustments, withholds, and per-merchant residual breakdowns for any reporting period.

#### Processor profiles

Retrieve complete TSYS processor profile data — card network acceptance, banking details, interchange qualification, hierarchy, and more — for any merchant in your portfolio.

## API basics

| Property           | Value                            |
| ------------------ | -------------------------------- |
| **Base URL**       | `https://getmodulate.dev`        |
| **Protocol**       | HTTPS only                       |
| **Format**         | JSON request and response bodies |
| **Authentication** | `X-Partner-API-Key` header       |
| **Versioning**     | URL-based (`/api/partner/...`)   |

## Rate limits

Each API key may make **120 requests per rolling 60-second window** unless we have raised its limit, shared across all endpoints. Limits are tracked per key, not per endpoint, so every key in your organization has its own budget. Exceeding the limit returns a `429 Too Many Requests` response with a `Retry-After` header indicating when you can resume.

| Budget            | Limit              | Applies to                                                           |
| ----------------- | ------------------ | -------------------------------------------------------------------- |
| Standard          | 120 / 60 s per key | Every endpoint except `GET /api/partner/rate-limit`                  |
| Rate-limit status | 60 / 60 s per key  | `GET /api/partner/rate-limit` only, instead of the standard budget   |
| AI                | 5 / 60 s per key   | `POST .../explain` endpoints, **in addition to** the standard budget |

An AI call counts against both the standard and the AI budget, and is refused with `429` if either is exhausted.

Every response carries your position in the budget that call was metered against. On data endpoints and `/me` that is the standard budget, so `X-RateLimit-Limit` reads `120` (or your key's raised limit); on `/rate-limit` itself the headers describe its own 60-request polling budget, while the response body reports your standard budget.

| Header                  | Meaning                                                  |
| ----------------------- | -------------------------------------------------------- |
| `X-RateLimit-Limit`     | Requests allowed in the window                           |
| `X-RateLimit-Remaining` | Requests still available                                 |
| `X-RateLimit-Reset`     | Unix timestamp when the oldest request leaves the window |

### Checking before you spend

`GET /api/partner/rate-limit` reports the same window for every active key in your organization, with the key you authenticated with listed first. Use it to pre-flight a batch job, or to see the separate AI budget that applies to `POST .../explain` — the headers above only reveal that budget once you have already called an AI endpoint.

```bash
curl https://getmodulate.dev/api/partner/rate-limit \
  -H "X-Partner-API-Key: YOUR_API_KEY"
```

Checking your status is metered against its own budget, so polling it does not consume the standard quota it reports.

> **Warning**
>
> If usage cannot be read, the response sets `"source": "unavailable"` and the `used`, `remaining`, and `reset_at` fields are `null` — that means **unknown**, not idle. Keep your own client-side counter rather than assuming a full budget.

> **Info**
>
> Need higher rate limits? Contact [it@flute.com](mailto:it@flute.com) to discuss your use case.

## Support

* **Email:** [it@flute.com](mailto:it@flute.com). Include the `meta.request_id` from the failing response.
* **Service levels:** [breaking-change notice, support response times, and what we measure](/partner-api/overview/getting-started/service-levels)
* **Partner Portal:** [withensemble.ai](https://withensemble.ai)