ACH Inquiry

Get the status for your ACH transactions

ACH Inquiry Endpoints

What you can do	Endpoint
Health check	get /accounts/transactions/v1/healthCheck
Search for ACH transactions	post /accounts/transactions/v1/ach/list
Get details about an ACH transaction with a PAR number	get /accounts/transactions/v1/ach/detail/{parNumber}
Get details for a settled ACH transaction	get /accounts/transactions/v1/ach/settled/{settlementTransactionId}

Key notes

Before you begin

To test or use any KeyBank API, you must be fully onboarded. This means having the right certificates, user credentials, and specific permissions for the API you're accessing.

Need help getting started? Check out our Get started section for everything you need to know.

Requirements

Account number

Use the financial institution account number (accountNumber) to look up related ACH transactions. This number cannot be more than 16 digits.

PAR number

When looking for details about an ACH transaction, use the Payment Assigned Reference (PAR) number. This is used to identify the transaction without exposing any sensitive consumer identification information. The /ach/list request generates a PAR number you can use in the /ach/detail request.

Learn more about how we use certain identifiers with ACH in our ACH User Guide.

Settlement transaction ID

To retrieve detailed transaction-level data (including batch item) for settled or returned ACH transactions, use the settlementTransactionId. This ID is returned as part of the response payloads from:

ACH Inquiry endpoints - the /ach/list or /ach/detail return the settlementTransactionId
Commercial Accounts Reporting API endpoints - the transactionId can be used as the settlement ID.

Interpret the response

ACH Inquiry response return two key fields with each response if it is for account information or transaction details: transaction type (transactionType) and status (transactionStatus).

Transaction type indicates if the transaction is a debit (collecting funds) or a credit (sending funds). The transaction code returns a two-digit number that indicates if it is a credit or debit for a checkings, savings, or loan account. Go to our Decoder to get additional details.

Transaction status displays the status of the transaction if it is in progress (COLLECTED), processed (SETTLED), or returned (RETURNED).

The consolidation settlement type affects what information is returned.

For clients with a non-consolidated settlement, you can receive information about collected, settled, and returned transactions.
For clients with a consolidated settlement, you will only receive collected and returned transactions. SETTLED is not an available status for consolidated settlement.

Health check

get /accounts/transactions/v1/healthCheck

Check the health of an API service and verify you can successfully connect. A bearer token is required.

Request example

curl "https://partner-api-qv.key.com/accounts/transactions/v1/healthCheck"
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
Status	string	Status of the health check response.
Source	string	Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestamp	string	Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIp	string	Client IP address the gateway receives from the request.
X-Forwarded-For	string	Sequence of IP addresses for systems between the client and the gateway.

Response example (200)

{
    "Status": "Ok",
    "Source": "Roundtrip",
    "Timestamp": "2022-09-15T04:49:03",
    "ClientIp": "192.0.2.1",
    "X-Forwarded-For": "[192.0.2.1]"
}

Search ACH transactions

post /accounts/transactions/v1/ach/list

Get a list of ACH transaction based on the on your search criteria.

Request

NAME	TYPE	DESCRIPTION
accountNumberrequired	string	The bank account number. This field cannot exceed 16 characters.
fromDaterequired	string	Start date for the date range. This date must be the current date or prior to the current date. Transaction data can be recalled within 180 days of the current date. Format: YYYY-MM-DD
toDaterequired	string	End date for the date range. This date can be the current day or a later date from the start date (fromDate). The date range should not be longer than 31 days. Format: YYYY-MM-DD"
minimumAmount	string	The minimum dollar amount of the transaction. This amount must be less than or equal to the maximum amount. Leave blank or enter zero for no minimum amount.
maximumAmount	string	The maximum dollar amount of the transaction. This amount must be greater than or equal to the minimum amount. Leave blank to retrieve all amounts. This amount cannot exceed one billion dollars.
traceNumber	string	The unique number for the transaction provided by the originator.
pageNumber	string	The number of the page being viewed. This number must be greater than or equal to 1.
pageSize	string	The total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.

Request example

{
    "accountNumber": "3123456789",
    "fromDate": "2024-02-01",
    "toDate": "2024-02-01",
    "minimumAmount": 100,
    "maximumAmount": 75020.5,
    "traceNumber": "043000090716192",
    "pageNumber": 1,
    "pageSize": 150
}

Responses

NAME	TYPE	DESCRIPTION
transactions	array	AchListTransaction
metadata	object	Metadata

Response example (200)

{
    "transactions": [
        {
            "parNumber": "22018007665985",
            "transactionStatus": "COLLECTED",
            "traceNumber": "043000090716192",
            "transactionAmount": 10.01,
            "collectionDate": "2021-03-07",
            "settlementDate": "2021-03-08",
            "transactionCode": "22",
            "transactionDescription": "DEPOSIT",
            "authorizedCustomerName": "TEST CUSTOMER1",
            "standardEntryClassCode": "CCD",
            "receivingAccount": {
                "accountNumber": "123456789012"
            },
            "receivingParty": {
                "customerIdentificationNumber": "099999999",
                "companyName": "MERCHANT"
            },
            "originatingAccount": {
                "accountNumber": "3123456789"
            },
            "originatingParty": {
                "customerIdentificationNumber": "1234567",
                "companyName": "COMPANY NAME 1"
            },
            "returnDate": "2024-02-01",
            "returnReasonCode": "R02",
            "returnReasonDescription": "Account Closed",
            "addendaCount": 1,
            "notificationOfChangeAddendaCount": 0,
            "internationalAddendaCount": 0,
            "settlementAmount": 123.45,
            "settlementTransactionId": "23218003015954"
        }
    ],
    "metadata": {
        "page": {
            "pageNumber": 1,
            "pageSize": 25,
            "totalPages": 3,
            "totalRecords": 75,
            "lastPage": false
        }
    }
}

Bad input parameter

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "AI-List-400-fromDate-105",
                    "message": "fromDate format must be YYYY-MM-DD"
                },
                {
                    "code": "AI-List-400-fromDate-117",
                    "message": "fromDate must be a valid date"
                }
            ]
        }
    }
}

Entitlements validation failed

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (403)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "403-Forbidden",
                    "message": "Entitlements Validation Failed"
                }
            ]
        }
    }
}

Unexpected server error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (500)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "500-InternalServerError",
                    "message": "An unexpected error occurred.  Please try again later or contact support if the problem persists."
                }
            ]
        }
    }
}

Get details about an ACH transaction with a PAR number

get /accounts/transactions/v1/ach/detail/{parNumber}

Use the parNumber to retrieve information about an ACH transaction. The parNumber can be obtained from the ACH List endpoint.

Request

path FIELD	TYPE	DESCRIPTION
parNumberrequired	string	The unique parNumber assigned to the transaction by the ACH processor.

Request example

curl --location: '{host}/accounts/transactions/v1/ach/detail/22018007665985'
--header 'Accept: application/json'
--header 'X-CorrelationId: 1234567890abcdef'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
parNumber	string	The unique parNumber assigned to the transaction by the ACH processor.
transactionStatus	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumber	string	The trace number provided in the detail record of the originators Nacha file.
transactionAmount	number	The dollar amount of the transaction.
collectionDate	string	The date the transaction collection occurred. Format: YYYY-MM-DD
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution. Defined by Nacha rules to indicate the type of transaction based on the account.
transactionCodeDescription	string	Description for the transaction code.
transactionDescription	string	Company Entry Description provided by the originator. Defined by Nacha specifications as a batch level description.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescription	string	The description for the Nacha SEC code.
receivingAccount	object	AccountDetail
receivingParty	object	PartyDetail
originatingAccount	object	AccountDetail
originatingParty	object	PartyDetail
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCode	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescription	string	Description as to why the ACH transaction is returned.
addendaCount	integer	Count of addenda records.
notificationOfChangeAddendaCount	integer	Count of change notifications records.
internationalAddendaCount	integer	Count of international addenda records.
customData	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.
checkSerialNumber	string	Serial number for the check converted to an ACH transaction.
transactionDirection	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
settlementAmount	number	The dollar amount of the settlement.
settlementTransactionId	string	The unique settlementTransactionId of the settled batch tied to the transaction.
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

Response example (200)

{
    "transactionStatus": "COLLECTED",
    "traceNumber": "043000090716192",
    "parNumber": "22018007665985",
    "transactionAmount": 10.01,
    "settlementDate": "2021-03-08",
    "collectionDate": "2021-03-07",
    "transactionCode": "22",
    "transactionDescription": "DEPOSIT",
    "authorizedCustomerName": "TEST CUSTOMER1",
    "standardEntryClassCode": "CCD",
    "receivingAccount": {
        "accountNumber": "123456789012",
        "routingNumber": "123456789",
        "bankNumber": "0000"
    },
    "receivingParty": {
        "customerIdentificationNumber": "099999999",
        "companyName": "MERCHANT",
        "customerName": "TEST MERCHANT"
    },
    "originatingAccount": {
        "accountNumber": "3123456789",
        "routingNumber": "1234567890",
        "bankNumber": "0000"
    },
    "originatingParty": {
        "customerIdentificationNumber": "1234567",
        "companyName": "COMPANY NAME 1",
        "customerName": "CUSTOMER NAME 1"
    },
    "returnReasonCode": "R02",
    "returnReasonDescription": "Account Closed",
    "returnDate": "2024-02-01",
    "addendaCount": 1,
    "notificationOfChangeAddendaCount": 0,
    "internationalAddendaCount": 0,
    "settlementAmount": 123.45,
    "settlementTransactionId": "23218003015954",
    "customData": "merchant:status",
    "checkSerialNumber": "4345",
    "transactionDirection": "Receiving Item",
    "standardEntryClassDescription": "Cash Concentration or Disbursement",
    "transactionCodeDescription": "Automated Deposit",
    "addenda": [
        {
            "sequenceNumber": 1,
            "entryDetailSequenceNumber": "188",
            "paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
        }
    ],
    "notificationOfChange": [
        {
            "changeCode": "C02",
            "changeDescription": "Incorrect transit/routing number",
            "correctedData": "1234567890"
        }
    ]
}

No ACH transaction was found with the provided parNumber

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (404)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/detail/22018007665985",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "AI-Detail-404-no-records-100",
                    "message": "Record Not Found"
                }
            ]
        }
    }
}

Unexpected server error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (500)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/detail/22018007665985",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "500-InternalServerError",
                    "message": "An unexpected error occurred.  Please try again later or contact support if the problem persists."
                }
            ]
        }
    }
}

Get details for a settled ACH transaction

get /accounts/transactions/v1/ach/settled/{settlementTransactionId}

Search for ACH batch details of transactions that have posted to the KeyBank account where the status is settled or returned.

Request

path FIELD	TYPE	DESCRIPTION
settlementTransactionIdrequired	string	The transaction ID that is assigned during settlement. This can be obtained from the Commercial Accounting API.

query FIELD	TYPE	DESCRIPTION
pageNumberoptional	integer	The number of the page being viewed. This number must be greater than or equal to 1.
pageSizeoptional	integer	The number of records per page. Must be between 1 and 1000.

Request example

curl --location: '{host}/accounts/transactions/v1/ach/settled/23218003015954?pageNumber=1&pageSize=150'
--header 'Accept: application/json'
--header 'X-CorrelationId: 1234567890abcdef'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

NAME	TYPE	DESCRIPTION
transactions	array	AchSettledTransaction
metadata	object	Metadata

Response example (200)

{
  "transactions": [
    {
      "parNumber": "22018007665985",
      "transactionStatus": "SETTLED",
      "traceNumber": "043000090716192",
      "transactionAmount": 10.01,
      "collectionDate": "2021-03-07",
      "settlementDate": "2021-03-08",
      "transactionCode": "22",
      "transactionDescription": "DEPOSIT",
      "authorizedCustomerName": "TEST CUSTOMER1",
      "standardEntryClassCode": "CCD",
      "receivingAccount": {
        "accountNumber": "123456789012"
      },
      "receivingParty": {
        "customerIdentificationNumber": "099999999",
        "companyName": "MERCHANT"
      },
      "originatingAccount": {
        "accountNumber": "3123456789"
      },
      "originatingParty": {
        "customerIdentificationNumber": "1234567",
        "companyName": "COMPANY NAME 1"
      },
      "settlementAmount": 123.45,
      "settlementTransactionId": "23218003015954"
    }
  ],
  "metadata": {
    "page": {
      "pageNumber": 1,
      "pageSize": 10,
      "totalPages": 3,
      "totalRecords": 28,
      "lastPage": false
    }
  }
}

Bad input parameter

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "AI-List-400-fromDate-105",
                    "message": "fromDate format must be YYYY-MM-DD"
                },
                {
                    "code": "AI-List-400-fromDate-117",
                    "message": "fromDate must be a valid date"
                }
            ]
        }
    }
}

No ACH transaction was found with the provided settlementTransactionId

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (404)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/settled/22018007665985",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "AI-Settled-404-no-records-100",
                    "message": "Record Not Found"
                }
            ]
        }
    }
}

Unexpected server error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (500)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "https://partner-api-qv.key.com/accounts/transactions/v1/ach/settled/22018007665985",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "500-InternalServerError",
                    "message": "An unexpected error occurred.  Please try again later or contact support if the problem persists."
                }
            ]
        }
    }
}

Schemas

AccountList

NAME	TYPE	DESCRIPTION
accountNumber	string	Bank account number.

AccountDetail

NAME	TYPE	DESCRIPTION
accountNumber	string	Bank account number of the ACH originator or receiver.
bankNumber	string	Bank number associated with the account number.
routingNumber	string	Nine-digit routing number for the account provided in the original request.

AchListTransaction

NAME	TYPE	DESCRIPTION
parNumber	string	The unique parNumber assigned to the transaction by the ACH processor.
transactionStatus	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumber	string	The trace number provided in the detail record of the originators Nacha file.
transactionAmount	number	The dollar amount of the transaction.
collectionDate	string	The date the transaction collection occurred. Format: YYYY-MM-DD
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution. Defined by Nacha rules to indicate the type of transaction based on the account.
transactionDescription	string	Company Entry Description provided by the originator. Defined by Nacha specifications as a batch level description.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	The three-digit Standard Entry Class code based on Nacha rules.
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCode	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescription	string	Description as to why the ACH transaction is returned.
addendaCount	integer	Count of addenda records.
notificationOfChangeAddendaCount	integer	Count of change notifications records.
internationalAddendaCount	integer	Count of international addenda records.
settlementAmount	number	The dollar amount of the settlement.
settlementTransactionId	string	The unique parNumber of the settlement batch tied to the transaction.

AchSettledTransaction

NAME	TYPE	DESCRIPTION
parNumber	string	The unique parNumber assigned to the transaction by the ACH processor.
transactionStatus	string	The status of the ACH transaction. Valid values: RETURNED, SETTLED
traceNumber	string	The trace number provided in the detail record of the originators Nacha file.
transactionAmount	number	The dollar amount of the transaction.
collectionDate	string	The date the transaction collection occurred. Format: YYYY-MM-DD
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution. Defined by Nacha rules to indicate the type of transaction based on the account.
transactionDescription	string	Company Entry Description provided by the originator. Defined by Nacha specifications as a batch level description.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	The three-digit Standard Entry Class code based on Nacha rules.
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCode	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescription	string	Description as to why the ACH transaction is returned.
settlementAmount	number	The dollar amount of the settlement.
settlementTransactionId	string	The unique parNumber of the settlement batch tied to the transaction.

Addendum

NAME	TYPE	DESCRIPTION
sequenceNumber	integer	The addenda record item number in order of sequence. Number cannot exceed 4 digits.
entryDetailSequenceNumber	string	The entry number in order of sequence. Number cannot exceed 7 digits.
paymentRelatedInformation	string	The related payment information from the addenda records. The maximum character limit is 255.

PartyList

NAME	TYPE	DESCRIPTION
customerIdentificationNumber	string	The unique identification number associated with the customer.
companyName	string	The name of the corporation or institution making the request.

PartyDetail

NAME	TYPE	DESCRIPTION
customerIdentificationNumber	string	The unique identification number associated with the customer.
companyName	string	The name of the corporation or institution making the request.
customerName	string	The name of the customer.

NotificationOfChange

NAME	TYPE	DESCRIPTION
changeCode	string	The three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
changeDescription	string	The description associated with the change code.
correctedData	string	The corrected data per the correction change code.

Message

NAME	TYPE	DESCRIPTION
code	string	Static code assigned by the network or payment system.
message	string	A human-readable message associated with the code.

Page

NAME	TYPE	DESCRIPTION
pageNumber	integer	The number of the page being viewed.
pageSize	integer	The number of records per page.
totalPages	integer	The total number of pages available.
totalRecords	integer	The total number of transactions (records) available in the result set.
lastPage	boolean	Indicates the last page of the total pages.

PageMetadata

NAME	TYPE	DESCRIPTION
page	Object	Page

Exception

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

ServiceErrorData

NAME	TYPE	DESCRIPTION
metadata	Object	ErrorMetadata

ConnectError

NAME	TYPE	DESCRIPTION
ConnectError	string	API connectivity error information, if available.

ErrorMetadata

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message

Errors

This API follows KeyBank standard error messaging, using the exception schema to provide error information. For more information about general errors, see Error handling.

Error responses are consistent across most endpoints and use one or more of the following HTTP status codes.

HTTP Status Code	Summary	Action
400	Invalid parameters The required information needed for an accepted request is not present.	Check the required fields and that the values meet the format and input requirements. For GET methods, you may need to include header information. Try `X-CorrelationId` as a header in the request. This is an optional ID, but sometimes inclusion in the request allows the GET method to perform correctly. Insert the `Accept` header with the `application/json` value to define the payload format.
403	Invalid entitlements The credentials provided are incorrect or access to this resource is denied.	Make sure the bearer token has not expired. Make sure to include the bearer token in each call.
404	No records found No data was found based on the criteria provided	Confirm the main identifier used in the request is correct, whether that be the `accountNumber`, `parNumber`, or `settlementTransactionId`.
500	Network or database errors This indicates a backend or system issue.	For backend issues, this typically requires investigation by KeyBank support.

Changelog

2.1.2

June 2026 | MID impact

New ACH settled endpoint released with related schemas - /accounts/transactions/v1/ach/settled/{settlementTransactionId}. Use the settlementTransactionId along with pagination controls to retrieve settlement or return details for ACH transactions.
Improved error messaging to be consistent across endpoints:
- 400 for invalid parameters
- 404 for non-existent IDs or lack of entitlement
- 500 for generic database or network errors

2.1.1

April 2026 | LOW impact

Added parameters collectionDate and transactionDescription to schemas AchListTransaction and AchDetailTransaction.

2.1.0

February 2026 | MID impact

We expanded upon settlement information for transaction list and transaction detail inquiries, adding the following two parameters: settlementAmount and settlementTransactionId.

2.0.0

October 2025 | MID impact

Deprecated legacy endpoints:

/accounts/transactions/v1/ACHStatusInquiry/list
/accounts/transactions/v1/collectedACHtransactions/list:
/accounts/transactions/v1/postedACHtransactions/list
/accounts/transactions/v1/postedACHtransactions/list

1.2.2

March 2025 | LOW impact

Deprecated dateSearchType from the request body in the /ach/list endpoint. You can no longer use the ACH status to filter your request. Look in the response body to view the AchStatus.

1.2.1

October 2024 | LOW impact

Date parameters adjusted to support the maximum date range search limit of 180 days. Do not enter a fromDate and toDate date range that goes beyond 31 days.

1.2.0

May 2024 | MID impact

Two new endpoints available in all environments, including the API simulator! We have added:

/accounts/transactions/v1/ach-transactions/{parNumber}
/accounts/transactions/v1/ach-transactions

1.1.6

December 2023 | MID impact

Deprecated the mdmID field. Backend services and processes have been enhanced to authenticate client API calls without the need for an MDM ID.
Removed the POSTED status from the list of valid values for the ACHStatus field in the achStatusInquiryResult object. Valid values for this field now only include COLLECTED or RETURNED.

1.1.5

September 2023 | LOW impact

The mdmId description has been updated to communicate that this field will soon deprecate in an upcoming release.

1.1.4

August 2023 | LOW impact

Modified the format for date parameters to match with KeyBank API standard date format of YYYY-MM-DD.
fromDate and toDate were updated to recall transaction data from the previous 24 months.

1.1.3

July 2023 | LOW impact

Added the settlementDate field in the response to provide you the ability to filter by date in response.
MDM ID (mdmId) is no longer a required field, it is now optional.

1.1.2

May 2023 | MID impact

Added customData to the following objects:
- achCollectedTransactionsResult
- achPostedTransactionsResult
- ACHReturnTransaction
Added receivingCustIdentificationNumber to the request payloads.
In the achCollectedTransactionsResult response, we added an example for the nonIatAddendum schema.

1.0.0

December 2022

Released on the Developer Portal.

Impact levels

LOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.
MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.
HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product.

YAML file

ACH Inquiry Endpoints

Key notes

Before you begin

Requirements

Account number

PAR number

Settlement transaction ID

Interpret the response

Health check

Request example

Responses

Successful response

Response example (200)

Search ACH transactions

Request

Request example

Responses

Response example (200)

Bad input parameter

Response example (400)

Entitlements validation failed

Response example (403)

Unexpected server error

Response example (500)

Get details about an ACH transaction with a PAR number

Request

Request example

Responses

Successful response

Response example (200)

No ACH transaction was found with the provided parNumber

Response example (404)

Unexpected server error

Response example (500)

Get details for a settled ACH transaction

Request

Request example

Responses

Response example (200)

Bad input parameter

Response example (400)

No ACH transaction was found with the provided settlementTransactionId

Response example (404)

Unexpected server error

Response example (500)

Schemas

AccountList

AccountDetail

AchListTransaction

AchSettledTransaction

Addendum

PartyList

PartyDetail

NotificationOfChange

Message

Page

PageMetadata

Exception

ServiceErrorData

ConnectError

ErrorMetadata

Errors

Changelog

2.1.2

2.1.1

2.1.0

2.0.0

1.2.2

1.2.1

1.2.0

1.1.6

1.1.5

1.1.4

1.1.3

1.1.2

1.0.0

Impact levels

We value your feedback