---
title: "List return requests"
method: GET
path: "/return_requests"
tags: ["Return Requests"]
---

# List return requests

`GET /return_requests`

List and filter return requests.

## Query parameters

- `limit` integer
- `starting_after` string
- `sort_order` 'asc' | 'desc'
- `connected_account_id` string
- `type` 'sepa' | 'sepa_instant'
- `status` 'received' | 'sent' | 'accepted' | 'rejected' | 'pending' | 'denied'
- `return_reason` string
- `related_payment_id` string, uuid
- `related_payment_type` 'payment_order' | 'incoming_payment'
- `start_date` string, date
- `end_date` string, date
- `start_value_date` string, date
- `end_value_date` string, date
- `file_id` string

## Response `200`

List of filtered return requests.

- ReturnRequestSearchResult
  - `records` ReturnRequestDetails[]
    - `id` string, uuid, required — The UUID of the return request.
    - `object` 'return_request', required — Label used to identify this kind of object
    - `type` 'sepa' | 'sepa_instant', required — The payment scheme or network. Only `sepa` and `sepa_instant` are supported for now.
    - `connected_account_id` string, uuid, required — The ID of the connected account.
    - `related_payment_id` string, uuid, required — The ID of the payment being returned, either an incoming payment or a payment order.
    - `related_payment_type` 'payment_order' | 'incoming_payment', required — The type of the payment corresponding to the return request. It can be an incoming payment or a payment order.
    - `return_reason` string, required — The reason for asking the payment's return. Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](https://docs.numeral.io/reference/sepa-reason-codes).
    - `status` 'received' | 'accepted' | 'denied' | 'rejected' | 'pending' | 'failed' | 'sent', required — The lifecycle stage of this return request. It will be updated as the return request is processed. See [return request's lifecycle](https://docs.numeral.io/reference/returns-lifecycle).
    - `status_details` string, required — The details of the status of this return request.
    - `metadata` object, required — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).
    - `bank_data` object, required — Bank data, such as message and transaction IDs, in JSON format.
      - `file_id` string, uuid, required
      - `message_id` string, required
      - `transaction_id` string, required
      - `end_to_end_id` string, required
    - `created_at` string, date-time, required — The UTC timestamp of the creation of this return request.
    - `additional_information` string[], required — Additional free-text information provided by the bank when denying a return request (populated from the `<AddtlInf>` field of the inbound camt.029 message). Empty array when no additional information was provided.

## Other responses

- `400` — Validation error.
- `500` — Internal server error.

---

[API](https://skmtc.net/numeral/apis/payments.md) · [All operations](https://skmtc.net/numeral/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral/payments/revisions/220f101cc2ef/schema)