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

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 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 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)

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:

{
  "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.

{
  "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".