---
title: "List requests"
method: GET
path: "/v2/requests"
tags: ["Requests"]
---

# List requests

`GET /v2/requests`

OAuth scope: `organization.read`

_This endpoint is only accessible by organizations in a Business or Enterprise plan._

---
Retrieve all requests within an organization.

---
The response contains the list of requests linked to the authenticated organization.
This allows to include request updates and treatment in any other workflows or tools
used for the day-to-day work.

---

## Attributes details

#### Request Type
`request_type` is an array that can take 4 different values:
- `flash_card`: a flash card is a non-physical card with a budget and a last day of validity.
  The card becomes inactive after the budget is totally spent or the last date of validity is past.
- `virtual_card`: a virtual card is a non-physical card with a monthly budget.
  Card holder can spend that amount every calendar month. Above that, transactions will be refused.
- `transfer`: a transfer of money from one Qonto account to another account.
- `multi_transfer`: several transfers executed at the same time.
  A document can be provided to create a multi-transfer which is composed of many different transfers.

#### Status
`status` is an array that can take 4 different values:

- `pending`: the request is waiting for a final status.
- `approved`: the request has been approved by one of the authorized members.
  All admins and owners can approve a request.
- `declined`: the request has been declined by one of the authorized members.
  All admins and owners can decline a request.
- `canceled`: the request has been canceled by its initiator.

#### Initiator ID
`initiator_id`: ID of the membership that initiated the request. When the request is initiated through the API, the initiator is the authenticated membership.

#### Approver ID
`approver_id:` Identifier of the membership who either approved or declined the request.
It matches with the ID of the membership object.

#### Note
`note`: mandatory note to explain the reason of the request.
This is a free format note.

#### Declined note
`declined_note`: it's a free format field filled in by the membership who declined the request.

#### Dates
- `created_at`: timestamp of creation of the request.
  Example: `2019-01-10T11:47:53.123Z`.
- `processed_at`: timestamp of when the request decision is taken.
  Either Approved or Declined by an admin. Or canceled by the requester.
  Example: `2019-01-10T11:47:53.123Z`.

#### Currency
`currency`: Must be EUR. ISO 4217 formatted.

#### Flash Card
The following fields are only present when `request_type = "flash_card"`.

- `pre_expires_at`: expiry date has been chosen by the requester during the request creation.
  Expires happen always at midnight.
  Example: `2023-06-17T23:59:59Z`.
- `payment_lifespan_limit`: maximum amount to be spent with that card in total.
  This amount is in the currency of `currency`.
  Example: `"1500.00"`.

#### Virtual Card
The following fields are only present when `request_type = virtual_card`.

- `payment_monthly_limit`: maximum amount to be spent with that card in total, per calendar month.
  This amount is in the currency of `currency`.
  Example: `"1500.00"`.

#### Transfer
The following fields are only present when `request_type = transfer`.

- `amount`: exact amount of the transfer to be approved.
  This amount is in the currency of `currency`.
  Example: `"1234.56"`.
- `recurrence`: when it's not `null`, it means that transfer will be recreated
  on the given frequency until `last_date_recurrence`.
  Can be `null`, or `weekly` or `monthly`.
- `last_recurrence_date`: limit date of the recurring transfer.
  No transfer happens after this date.
  Example: `2019-01-15`
- `creditor_name`: full name of the beneficiary of the transfer. Max 140 chars long.
- `scheduled_date`: Can be set by the requester to send the transfer later and not immediately.
  Can only be set in the future by the requester. Defaults to current date or next banking day.
  Example: `2019-01-15`.

#### Multi-Transfer
The following fields are only present when `request_type = multi_transfer`.

- `total_transfers_amount`: sum of all transfers amounts included in the multi-transfer.
  This amount is in the currency of `total_transfers_amount_currency`.
  Example: `"1234.56"`
- `total_transfers_amount_currency`: Must be EUR. ISO 4217 formatted.
  Only Request in EUR are allowed. Allowed values:`EUR`.
- `total_transfers_count`: number of transfers included in the multi-transfer.
- `scheduled_date`: Can be set by the requester to send the transfer later and not immediately.
  Can only be set in the future by the requester. Defaults to current date or next banking day.
  Example: `2019-01-15`.

## Filters
`status`

Requests can be filtered by status. The **`status`** query parameter accepts an array
of statuses as value. Here is what statuses correspond to:

- `pending`: a request still waiting for final status.
- `approved`: a request that has been approved by approver. Final status.
- `declined`: a request that has been declined by approver. Final status.
- `canceled`: a request that has been canceled by requester. Final status.

For example, if you want to retrieve several requests statuses, you can use the following filter: `status[]=approved&status[]=declined&status[]=pending`

**Do note**: *If no `status` is specified, the API will return all the requests.*
<br/>
<br/>

`request_type`

Requests can be filtered by type. The `request_type` query parameter accepts an array of
statuses as value. Here is what request types correspond to:

- `flash_card`: a flash card is a non-physical card with a budget and a last day of validity.
  The card becomes inactive after the budget is totally spent or the last date of validity is past.
- `virtual_card`: a virtual card is a non-physical card with a monthly budget.
  Card holder can spend that amount every calendar month. Above that, transactions will be refused.
- `transfer`: a transfer of money from one Qonto account to another account.
- `multi_transfer`: several transfers executed at the same time.
  A document can be provided to create a multi-transfer which is composed of many different transfers.

**Do note**: *If no `request_type` specified, the API will return all the requests.*
<br/>
<br/>

`processed_at_from` / `created_at_from`

Requests can be filtered according to both `processed_at` and `created_at` fields.
This is particularly useful to retrieve only the latest updated requests in your application.
Two filters are available:

- `processed_at_from`: minimum value (e.g: `2019-01-10T11:47:53.123Z`).
- `created_at_from`: minimum value  (e.g: `2019-01-10T11:47:53.123Z`).

**Do note**: *`processed_at_from` / `created_at_from` filters should have a valid date time format (**ISO 8601** for instance)*

## Sorting
Request list can be sorted by a specific field and order.
The `sort_by` query parameter accepts a string defining these two items with the `field:order` format.

- `processed_at`: when request was processed.
    Two values are available: `asc` (ascending) / `desc` (descending)

- `created_at`: when request was created.
    Two values are available: `asc` (ascending) / `desc` (descending)

- `status`: reflects the information about the request status.
    Two values are available: `asc` (ascending) / `desc` (descending).
    Sorting by ascending gives a list of request with statuses in the given order: `pending`, `approved`, `declined`, `canceled`.

**Do note**: *Use a combination of field and order to define how to sort the transfer list (e.g **`processed_at:asc`**).*
*By default, requests are sorted by `created_at:desc`.*

## Pagination
Default number of items per page is 25. [See Schema here](https://api-doc.qonto.com/docs/business-api/c2NoOjI3NTA2MjA3-pagination).

## Query parameters

- `status` string[]
- `request_type` string[]
- `created_at_from` string, date-time
- `processed_at_from` string, date-time
- `sort_by` 'created_at:asc' | 'created_at:desc' | 'processed_at:asc' | 'processed_at:desc' | 'status:asc' | 'status:desc'

## Headers

- `X-Qonto-Staging-Token` string

## Response `200`

lists requests for a given organization

- object
  - `requests` union[], required
    - union
      - RequestFlashCard — A virtual card with a budget and a last day of validity. The card becomes inactive after the budget is totally spent or the last date of validity is past
        - `id` string, uuid — ID of the request
        - `request_type` 'flash_card' — Type of the request
        - `status` 'pending' | 'approved' | 'declined' | 'canceled' — Status of the request
        - `initiator_id` string, uuid — ID of the membership that initiated the request. <br>When the request is initiated through the API, the initiator is the authenticated membership.
        - `approver_id` string, uuid, nullable — ID of the membership that approved the request
        - `note` string — Reason for the request
        - `declined_note` string, nullable — Reason why the request was declined
        - `pre_expires_at` string, date-time — When the flash card expires
        - `payment_lifespan_limit` string — Total of payment limit until card expires
        - `currency` string — Currency of the card and its limits. ISO-4217 3-characters currency code
        - `processed_at` string, date-time, nullable — When request was approved, canceled or declined
        - `created_at` string, date-time — When request was created
      - RequestVirtualCard — A virtual card with a monthly budget. Card holder can spend that amount every calendar month. Above that, transactions will be refused
        - `id` string, uuid — ID of the request
        - `request_type` 'virtual_card' — Type of the request
        - `status` 'pending' | 'approved' | 'declined' | 'canceled' — Status of the request
        - `initiator_id` string, uuid — ID of the membership that initiated the request. <br>When the request is initiated through the API, the initiator is the authenticated membership.
        - `approver_id` string, uuid, nullable — ID of the membership that approved the request
        - `note` string — Reason for the request
        - `declined_note` string, nullable — Reason why the request was declined
        - `payment_monthly_limit` string — Total of payment limit by month
        - `currency` string — Currency of the card and its limits. ISO-4217 3-characters currency code
        - `processed_at` string, date-time, nullable — When request was approved, canceled or declined
        - `created_at` string, date-time — When request was created
      - RequestMultiTransfer — Several transfers executed at the same time. Several format can be provided to create a bulk transfer which is composed of many different transfers
        - `id` string, uuid — ID of the request
        - `request_type` 'multi_transfer' — Type of the request
        - `status` 'pending' | 'approved' | 'declined' | 'canceled' — Status of the request
        - `initiator_id` string, uuid — ID of the membership that initiated the request. <br>When the request is initiated through the API, the initiator is the authenticated membership.
        - `approver_id` string, uuid, nullable — ID of the membership that approved the request
        - `note` string — Reason for the request
        - `declined_note` string, nullable — Reason why the request was declined
        - `total_transfers_amount` string — Total amount of the transfers, example "2152.25"
        - `total_transfers_amount_currency` string — Currency of the transfers. ISO-4217 3-characters currency code
        - `total_transfers_count` integer — Number of transfers
        - `scheduled_date` string, date — When transfers would be executed. If request is approved after this date, they will be executed immediately
        - `processed_at` string, date-time, nullable — When request was approved, canceled or declined
        - `created_at` string, date-time — When request was created
      - RequestTransfer — A transfer of money from one Qonto account to another account
        - `id` string, uuid — ID of the request
        - `request_type` 'transfer' — Type of the request
        - `status` 'pending' | 'approved' | 'declined' | 'canceled' — Status of the request
        - `initiator_id` string, uuid — ID of the membership that initiated the request. <br>When the request is initiated through the API, the initiator is the authenticated membership.
        - `approver_id` string, uuid, nullable — ID of the membership that approved the request
        - `note` string — Reason for the request
        - `declined_note` string, nullable — Reason why the request was declined
        - `creditor_name` string — Name of the beneficiary
        - `amount` string — Amount of the transfer, example "152.25"
        - `currency` string — Currency of the transfer. ISO-4217 3-characters currency code
        - `scheduled_date` string, date — When transfer would be executed. If request is approved after this date, it will be executed immediately
        - `recurrence` 'weekly' | 'monthly', nullable — Tells if transfer is recurring, null if it is not
        - `last_recurrence_date` string, date-time, nullable — Date of the last recurrence
        - `processed_at` string, date-time, nullable — When request was approved, canceled or declined
        - `created_at` string, date-time — When request was created
  - `meta` Pagination, required
    - `current_page` integer
    - `next_page` integer, nullable
    - `prev_page` integer, nullable
    - `total_pages` integer
    - `total_count` integer
    - `per_page` integer

## Other responses

- `422` — Returns errors

---

[API](https://skmtc.net/hiit-consulting-fr/apis/qonto.md) · [All operations](https://skmtc.net/hiit-consulting-fr/apis/qonto/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hiit-consulting-fr/qonto/revisions/25208d6f9deb/schema)