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

# Diameter API Reference Overview

> Complete REST API reference for the Diameter banking platform. Base URLs, versioning, request format, pagination, and error handling.

The Diameter API is a REST API that enables fintechs to onboard end users, manage virtual accounts, create counterparties, and process domestic and international wire payments through Diameter's partner bank network. All API interactions follow standard HTTP conventions and exchange data as JSON. This page covers everything you need to know to form valid requests and interpret responses — authentication, idempotency, pagination, error handling, and the data formats used throughout the API.

## Base URLs

The API is available in two environments. Use the sandbox environment for all development and testing. Only production-ready, verified integrations should connect to the production environment.

| Environment | Base URL |
| - | - |
| Sandbox | `https://api.sandbox.diameterpay.com` |
| Production | `https://api.prod.diameterpay.com` |

> [!WARNING]
>
> Some endpoints are sandbox-only and will return `403 Forbidden` if called against the production base URL. These endpoints are clearly marked in their individual reference pages.

## API Version

The current API version is **0.11.7**. The version is reflected in all endpoint paths (e.g., `/v1/accounts`). See the [Changelog](https://diameterpay.mintlify.site/changelog.md) for the full release history.

## Authentication

All requests must include a valid Bearer token in the `Authorization` header:

```
Authorization: Bearer <your_access_token>
```

Tokens are JWTs that encode the scopes your integration is authorized to use. Each endpoint requires a specific scope (e.g., `com.diameterpay.api/accounts.read`, `com.diameterpay.api/end-users.write`). Requests made with a token that is missing the required scope receive a `403 Forbidden` response. For instructions on obtaining tokens, see the [Authentication](https://diameterpay.mintlify.site/authentication.md) page.

## Content Type

All request and response bodies use JSON. Set the `Content-Type` header on every request that includes a body:

```
Content-Type: application/json
```

## Idempotency

All write requests (`POST`, `PUT`, `PATCH`) require an `x-idempotency-key` header containing a UUID v4 value. Idempotency keys protect against duplicate operations caused by network retries or client errors.

```
x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000
```

| Scenario | Behavior |
| - | - |
| Same key + same payload (repeated) | Safe — returns the original response |
| Same key + different payload | `409 Conflict` (`ERR_7006`) |
| Same key while original request is still processing | `409 Conflict` (`ERR_7003`) |

> [!TIP]
>
> Generate a fresh UUID v4 for each logically distinct operation. Reuse the same key only when retrying after a network failure where you did not receive a response.

## Pagination

List endpoints return paginated results. Control pagination with the following query parameters:

| Parameter | Default | Maximum | Description |
| - | - | - | - |
| `page` | `1` | `10000` | Page number to retrieve |
| `limit` | `10` | `100` | Number of results per page |

Every paginated response includes a `pagination` object:

```json theme={null}
{
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "totalPages": 5,
    "isLast": false
  }
}
```

| Field | Description |
| - | - |
| `page` | The current page number |
| `limit` | The number of results per page as requested |
| `total` | Total number of matching records across all pages |
| `totalPages` | Total number of pages available |
| `isLast` | `true` when the current page is the last page |

## Error Responses

When a request fails, the API returns a structured error response body alongside the appropriate HTTP status code. The `requestId` uniquely identifies the failed request and should be included when contacting Diameter support.

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1704067200000,
  "error": {
    "statusCode": 400,
    "message": "Validation failed for the submitted data.",
    "code": "ERR_1301",
    "severity": "error",
    "details": [
      {
        "location": "body",
        "path": "email",
        "message": "Email format is invalid",
        "reason": "invalid"
      }
    ]
  },
  "metadata": {}
}
```

| Field | Description |
| - | - |
| `requestId` | UUID identifying this specific request, for support and debugging |
| `timestamp` | Unix epoch milliseconds when the error occurred |
| `error.statusCode` | The HTTP status code |
| `error.message` | Human-readable summary of the error |
| `error.code` | Machine-readable error code (e.g., `ERR_1301`) |
| `error.severity` | Severity level — typically `error` or `warning` |
| `error.details` | Array of field-level validation errors (present on `400` responses) |
| `error.details[].location` | Where the invalid value was found (`body`, `query`, `path`) |
| `error.details[].path` | The field name or JSON path of the invalid value |
| `error.details[].message` | Description of the specific validation failure |
| `error.details[].reason` | Short reason code (e.g., `invalid`, `required`, `too_long`) |

## HTTP Status Codes

The API uses standard HTTP status codes to communicate the outcome of each request.

| Status | Meaning |
| - | - |
| `200` | Success |
| `201` | Created |
| `204` | No Content — returned on successful `DELETE` requests |
| `400` | Validation error — check `error.details` for field-level messages |
| `401` | Unauthorized — the token is missing, expired, or invalid |
| `403` | Forbidden — the token lacks the required scope, or a sandbox-only endpoint was called in production |
| `404` | Resource not found |
| `409` | Conflict — idempotency key reuse with a different payload |
| `429` | Rate limited — slow down requests and retry with back-off |
| `5XX` | Server error — an unexpected error occurred on the Diameter side |

## Data Formats

The Diameter API uses consistent formats for IDs, dates, amounts, and currency across all endpoints.

**IDs**

All resource identifiers (accounts, payments, end users, counterparties, etc.) use **UUID v4** format:

```
550e8400-e29b-41d4-a716-446655440000
```

**Dates and Timestamps**

Date-time values are formatted as **ISO 8601** strings in UTC:

```
2024-01-15T10:30:00Z
```

**Monetary Amounts**

Amounts are represented as **strings** with up to two decimal places:

```
"100.00"
```

Using strings avoids floating-point precision issues. Always parse amounts as strings (or use a decimal library) rather than as floating-point numbers.

**Currency**

Only **USD** is currently supported. The `currency` field in account and payment objects will always contain `"USD"`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.