> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List ACH Returns
>
The features documented here are in a beta state, and this documentation is considered draft material subject to frequent change.
Use this endpoint to get all ACH returns.
## OpenAPI
````yaml openapi/platform-api/v20111101.yaml GET /ach_returns
openapi: 3.0.0
info:
contact:
name: MX Platform API
url: https://www.mx.com/products/platform-api
description: >
The MX Platform API is a powerful, fully-featured API designed to make
aggregating and enhancing financial data easy and reliable. It can
seamlessly connect your app or website to tens of thousands of financial
institutions.
title: MX Platform API
version: '20111101'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: authorization
- name: widgets
- name: users
- name: members
- name: institutions
- name: accounts
- name: transactions
- name: microdeposits
- name: managed data
- name: transaction rules
- name: statements
- name: merchants
- name: categories
- name: insights
- name: investment holdings
- name: spending plan
- name: goals
- name: budgets
- name: monthly cash flow profile
- name: notifications
- name: taggings
- name: tags
- name: deprecated
- name: processor token
- name: verifiable credentials
- name: rewards
- name: ach return
paths:
/ach_returns:
get:
tags:
- ach return
summary: List ACH Returns
description: >
The features documented here are in a beta state, and this documentation
is considered draft material subject to frequent change.
Use this endpoint to get all ACH returns.
operationId: listACHRetruns
parameters:
- $ref: '#/components/parameters/institutionGuid'
- $ref: '#/components/parameters/returnedAt'
- $ref: '#/components/parameters/resolvedStatusAt'
- $ref: '#/components/parameters/returnCode'
- $ref: '#/components/parameters/returnStatus'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPage'
responses:
'200':
content:
application/vnd.mx.api.v1+json:
schema:
$ref: '#/components/schemas/ACHReturnsResponseBody'
description: OK
components:
parameters:
institutionGuid:
description: >-
The identifier for the institution associated with the ACH return.
Defined by MX.
in: query
name: institution_guid
required: false
schema:
type: string
returnedAt:
description: >-
The date and time when the return was reported by the Receiving
Financial Depository Institution (RDFI) in ISO 8601 format without
timestamp.
example: '2025-02-13T18:09:00+00:00'
in: query
name: returned_at
required: false
schema:
type: string
resolvedStatusAt:
description: >-
The date and time when the return was resolved by the Receiving
Financial Depository Institution (RDFI) in ISO 8601 format without
timestamp
example: '2025-02-13T18:09:00+00:00'
in: query
name: resolved_status_at
required: false
schema:
type: string
returnCode:
description: >-
The associated ACH return code and notice of change code. See [Return
Codes](/api-reference/platform-api/reference/ach-return-fields#return-codes)
for a complete list.
in: query
name: return_code
required: false
schema:
type: string
returnStatus:
description: >-
The status of the return. See [Return
Statuses](/api-reference/platform-api/reference/ach-return-fields#return-status)
for a complete list.
example: SUBMITTED
in: query
name: return_status
required: false
schema:
type: string
page:
description: Results are paginated. Specify current page.
example: 1
in: query
name: page
schema:
type: integer
recordsPerPage:
description: >-
This specifies the number of records to be returned on each page.
Defaults to `25`. The valid range is from `10` to `100`. If the value
exceeds `100`, the default value of `25` will be used instead.
example: 10
in: query
name: records_per_page
schema:
type: integer
schemas:
ACHReturnsResponseBody:
properties:
ach_returns:
items:
$ref: '#/components/schemas/ACHResponse'
type: array
pagination:
$ref: '#/components/schemas/PaginationResponse'
type: object
ACHResponse:
properties:
account_guid:
example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
nullable: false
type: string
account_number_last_four:
example: '1234'
nullable: true
type: string
account_type:
type: string
nullable: true
example: CREDIT
ach_initiated_at:
example: '2025-02-13T18:08:00+00:00'
nullable: true
type: string
client_guid:
example: CLT-abcd-1234
nullable: false
type: string
corrected_account_number:
example: null
nullable: true
type: string
corrected_routing_number:
example: null
nullable: true
type: string
created_at:
example: null
nullable: false
type: string
guid:
example: ACH-d74cb14f-fd0a-449f-991b-e0362a63d9c6
nullable: false
type: string
id:
example: client_ach_return_id_1234
nullable: false
type: string
institution_guid:
example: INS-34r4f44b-cfge-0f6e-3484-21f47e45tfv7
nullable: false
type: string
investigation_notes:
example: null
nullable: true
type: string
member_guid:
example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
nullable: false
type: string
processing_errors:
example: null
nullable: true
type: string
resolution_code:
example: null
nullable: true
type: string
resolution_detail:
example: null
nullable: true
type: string
resolved_status_at:
example: null
nullable: true
type: string
return_code:
example: R01
nullable: false
type: string
return_notes:
example: null
nullable: true
type: string
return_account_number:
example: null
nullable: true
type: string
return_routing_number:
example: null
nullable: true
type: string
return_status:
example: SUBMITTED
nullable: true
type: string
returned_at:
example: '2025-02-13T18:09:00+00:00'
nullable: true
type: string
sec_code:
example: PPD
nullable: true
type: string
started_processing_at:
example: null
nullable: true
type: string
submitted_at:
example: null
nullable: true
type: string
transaction_amount:
example: 225.84
format: double
nullable: true
type: number
updated_at:
example: null
nullable: false
type: string
user_guid:
example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
nullable: false
type: string
type: object
PaginationResponse:
properties:
current_page:
example: 1
type: integer
per_page:
example: 25
type: integer
total_entries:
example: 1
type: integer
total_pages:
example: 1
type: integer
type: object
securitySchemes:
basicAuth:
scheme: basic
type: http
````