> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List requests

> OAuth scope: `organization.read`

Retrieves the list of requests for the authenticated organizations.

You can filter (ex: only retrieve a specific request type) and sort this list by using [query parameters](#parameter-status) 👇

The response is automatically filtered based on the authenticated user's role and scope:
- **Employee**: Only their own requests
- **Manager (team-level permissions)**: 
  - Their own requests
  - Requests from direct team members
- **Manager (organization-level permissions)**: 
  - All the requests (based on their permissions)
- **Owner/Admin**: All the requests across the organization

<Info>
  **Price plans**: this endpoint is only accessible by organizations in a Business or Enterprise plan.
</Info>




## OpenAPI

````yaml get /v2/requests
openapi: 3.1.1
info:
  version: v2
  title: Qonto
servers:
  - url: https://thirdparty.qonto.com
    description: Production URL
  - url: https://thirdparty-sandbox.staging.qonto.co
    description: Sandbox URL
security:
  - OAuth:
      - organization.read
      - membership.read
      - membership.write
      - attachment.write
      - internal_transfer.write
      - payment.write
      - supplier_invoice.write
      - supplier_invoice.read
      - client_invoices.read
      - client_invoice.write
      - client.read
      - client.write
      - product.read
      - product.write
      - request_review.write
      - request_review.read
      - team.read
      - team.write
      - request_transfers.write
      - insurance_contract.read
      - insurance_contract.write
      - card.read
      - card.write
      - bank_account.write
      - beneficiary.trust
      - webhook
      - payment_link.write
      - payment_link.read
      - sepa_direct_debit.read
      - sepa_direct_debit.write
      - terminal.read
      - terminal.write
  - SecretKey: []
paths:
  /v2/requests:
    get:
      tags:
        - Requests
      summary: List requests
      description: >
        OAuth scope: `organization.read`


        Retrieves the list of requests for the authenticated organizations.


        You can filter (ex: only retrieve a specific request type) and sort this
        list by using [query parameters](#parameter-status) 👇


        The response is automatically filtered based on the authenticated user's
        role and scope:

        - **Employee**: Only their own requests

        - **Manager (team-level permissions)**: 
          - Their own requests
          - Requests from direct team members
        - **Manager (organization-level permissions)**: 
          - All the requests (based on their permissions)
        - **Owner/Admin**: All the requests across the organization


        <Info>
          **Price plans**: this endpoint is only accessible by organizations in a Business or Enterprise plan.
        </Info>
      operationId: list_requests
      parameters:
        - $ref: '#/components/parameters/X-Qonto-Staging-Token'
        - name: status[]
          in: query
          description: |-
            Requests can be filtered by their `status`.
            This filter accepts an array of the following statuses:
             `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.
          schema:
            type: array
            default: all statuses
            items:
              type: string
              enum:
                - pending
                - approved
                - canceled
                - declined
            example: status[]=approved&status[]=declined&status[]=pending
        - name: request_type[]
          in: query
          description: >-
            Requests can be filtered by their `request_type`.

            This filter accepts an array of the following  statuses:

            - `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.
          schema:
            type: array
            default: all request types
            items:
              type: string
              enum:
                - transfer
                - multi_transfer
                - flash_card
                - virtual_card
            example: request_type[]=transfer&request_type[]=multi_transfer
        - name: created_at_from
          in: query
          description: >-
            Requests can be filtered by their `created_at` property. Please use
            a valid date time format (ISO 8601 for instance).
          schema:
            type: string
            format: date-time
            example: '2019-01-10T11:47:53.123Z'
        - name: processed_at_from
          in: query
          description: >-
            Requests can be filtered by their `processed_at` property. Please
            use a valid date time format (ISO 8601 for instance).
          schema:
            type: string
            format: date-time
            example: '2019-01-10T11:47:53.123Z'
        - name: sort_by
          in: query
          description: >-
            Requests can be sorted by a specific property and order.

            Property: `processed_at`, `created_at` or `status`

            Order: `asc` (Ascending) / `desc` (Descending)


            **Do note**: Sorting by `status:asc` returns a list of requests with
            statuses in the following order: `pending`, `approved`, `declined`,
            `canceled`.
          schema:
            type: string
            default: created_at:desc
        - name: page
          in: query
          description: Returned page (cf. [Pagination](/get-started/general/pagination)).
          schema:
            type: string
        - name: per_page
          in: query
          description: >-
            Number of requests per page (cf.
            [Pagination](/get-started/general/pagination)).
          schema:
            type: string
      responses:
        '200':
          description: Returns the list of requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requests:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/RequestFlashCard'
                        - $ref: '#/components/schemas/RequestVirtualCard'
                        - $ref: '#/components/schemas/RequestMultiTransfer'
                        - $ref: '#/components/schemas/RequestTransfer'
                  meta:
                    $ref: '#/components/schemas/Pagination'
                required:
                  - requests
                  - meta
              examples:
                default:
                  value:
                    meta:
                      current_page: 1
                      next_page: null
                      prev_page: null
                      total_pages: 1
                      total_count: 4
                      per_page: 25
                    requests:
                      - id: 965b8c57-72fd-4d12-8d85-56874104c81a
                        request_type: virtual_card
                        status: pending
                        initiator_id: cc32875a-a590-44c7-bdc1-0680ae72b0db
                        approver_id: null
                        note: Library subscription
                        declined_note: null
                        payment_monthly_limit: '5.00'
                        currency: EUR
                        processed_at: null
                        created_at: '2021-11-24T10:34:51.706Z'
                      - id: fd6d72c0-557d-4d51-8502-d7ce86cb72ea
                        request_type: flash_card
                        status: canceled
                        initiator_id: dbbb579a-f8a5-41df-8cea-09e040464366
                        approver_id: null
                        note: Restaurant
                        declined_note: null
                        pre_expires_at: '2022-03-15T22:59:59.999Z'
                        payment_lifespan_limit: '250.00'
                        currency: EUR
                        processed_at: '2021-11-24T10:33:59.965Z'
                        created_at: '2021-11-24T10:33:23.817Z'
                      - id: 68e38bca-064c-4b50-8343-26ce40f617af
                        request_type: multi_transfer
                        status: approved
                        initiator_id: 300d309f-a7e0-4db2-af3b-003ce0a676a4
                        approver_id: 087a7f4f-d316-4bad-810f-84807634cb9f
                        note: Scheduled multi transfer (for Aug 2022)
                        declined_note: null
                        total_transfers_amount: '25561.80'
                        total_transfers_amount_currency: EUR
                        total_transfers_count: 43
                        scheduled_date: '2022-08-15'
                        processed_at: '2021-11-24T10:34:51.706Z'
                        created_at: '2021-11-10T12:22:28.790Z'
                      - id: 57d28d6f-3a22-4573-990a-c62d2f7d67f0
                        request_type: transfer
                        status: declined
                        initiator_id: dbbb579a-f8a5-41df-8cea-09e040464366
                        attachment_ids: []
                        approver_id: 788571b5-1aea-4aec-bb7b-366288a4ba68
                        note: Provider subscription
                        declined_note: This is not in our policy
                        creditor_name: John Doe
                        amount: '30.00'
                        currency: EUR
                        scheduled_date: '2021-10-06'
                        recurrence: monthly
                        last_recurrence_date: null
                        processed_at: '2021-10-06T16:14:28.284Z'
                        created_at: '2021-10-06T16:14:11.673Z'
        '400':
          $ref: '#/components/responses/400-Bad-request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '422':
          description: Returns an unprocessable entity error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    $ref: '#/components/schemas/UnprocessableEntityError'
                required:
                  - errors
              examples:
                Invalid filter:
                  value:
                    errors:
                      - code: invalid
                        detail: created_at_from is not a valid date
                        source:
                          properties:
                            pointer: /created_at_from
        '500':
          $ref: '#/components/responses/500-Internal-Server-Error'
      security:
        - OAuth:
            - organization.read
        - SecretKey: []
components:
  parameters:
    X-Qonto-Staging-Token:
      name: X-Qonto-Staging-Token
      in: header
      description: >-
        Required only for Sandbox API requests; to get one, please sign up to
        the [Developer Portal](https://developers.qonto.com/).
      schema:
        type: string
  schemas:
    RequestFlashCard:
      type: object
      properties:
        id:
          type: string
          example: 965b8c57-72fd-4d12-8d85-56874104c81a
        request_type:
          type: string
          example: flash_card
        status:
          type: string
          enum:
            - pending
            - approved
            - declined
            - canceled
          example: pending
        initiator_id:
          type: string
          description: ID of the membership that initiated the request
          example: cc32875a-a590-44c7-bdc1-0680ae72b0db
        approver_id:
          type:
            - string
            - 'null'
        note:
          type: string
          example: Library subscription
        declined_note:
          type:
            - string
            - 'null'
        payment_lifespan_limit:
          type: string
          example: '250.00'
        pre_expires_at:
          type: string
          format: date-time
          example: '2022-03-15T22:59:59.999Z'
        currency:
          type: string
          example: EUR
        processed_at:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
          example: '2021-11-24T10:33:23.817Z'
    RequestVirtualCard:
      type: object
      properties:
        id:
          type: string
          example: 965b8c57-72fd-4d12-8d85-56874104c81a
        request_type:
          type: string
          example: virtual_card
        status:
          type: string
          enum:
            - pending
            - approved
            - declined
            - canceled
          example: pending
        initiator_id:
          type: string
          description: ID of the membership that initiated the request
          example: cc32875a-a590-44c7-bdc1-0680ae72b0db
        approver_id:
          type:
            - string
            - 'null'
        note:
          type: string
          example: Library subscription
        declined_note:
          type:
            - string
            - 'null'
        payment_monthly_limit:
          type: string
          example: '5.00'
        currency:
          type: string
          example: EUR
        processed_at:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
          example: '2021-11-24T10:34:51.706Z'
        card_level:
          type: string
          description: Which card level was requested
          enum:
            - virtual
            - virtual_partner
          example: virtual
        card_design:
          type: string
          description: Design of the card that was requested
          example: virtual.default.2017
    RequestMultiTransfer:
      type: object
      properties:
        id:
          type: string
          example: 68e38bca-064c-4b50-8343-26ce40f617af
        request_type:
          type: string
          example: multi_transfer
        status:
          type: string
          enum:
            - pending
            - approved
            - declined
            - canceled
          example: approved
        initiator_id:
          type: string
          description: ID of the membership that initiated the request
          example: 300d309f-a7e0-4db2-af3b-003ce0a676a4
        approver_id:
          type: string
          example: 087a7f4f-d316-4bad-810f-84807634cb9f
        note:
          type: string
          example: Scheduled multi transfer (for Aug 2022)
        declined_note:
          type:
            - string
            - 'null'
        total_transfers_amount:
          type: string
          example: '25561.80'
        total_transfers_amount_currency:
          type: string
          example: EUR
        total_transfers_count:
          type: integer
          format: int32
          example: 43
        scheduled_date:
          type: string
          format: date
          example: '2022-08-15'
        processed_at:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
          example: '2021-11-10T12:22:28.790Z'
    RequestTransfer:
      type: object
      properties:
        id:
          type: string
          example: 57d28d6f-3a22-4573-990a-c62d2f7d67f0
        request_type:
          type: string
          example: transfer
        status:
          type: string
          enum:
            - pending
            - approved
            - declined
            - canceled
          example: declined
        initiator_id:
          type: string
          description: ID of the membership that initiated the request
          example: dbbb579a-f8a5-41df-8cea-09e040464366
        attachment_ids:
          type: array
          items:
            type: string
          example: []
        approver_id:
          type: string
          example: 788571b5-1aea-4aec-bb7b-366288a4ba68
        note:
          type: string
          example: Provider subscription
        declined_note:
          type: string
          example: This is not in our policy
        creditor_name:
          type: string
          example: John Doe
        amount:
          type: string
          example: '30.00'
        currency:
          type: string
          example: EUR
        scheduled_date:
          type: string
          format: date
          example: '2021-10-06'
        recurrence:
          type: string
          example: monthly
        last_recurrence_date:
          type:
            - string
            - 'null'
        processed_at:
          type: string
          format: date-time
          example: '2021-10-06T16:14:28.284Z'
        created_at:
          type: string
          format: date-time
          example: '2021-10-06T16:14:11.673Z'
    Pagination:
      type: object
      description: Metadata for paginated responses
      required:
        - current_page
        - next_page
        - prev_page
        - total_pages
        - total_count
        - per_page
      properties:
        current_page:
          type: integer
          description: The current page number
          example: 2
        next_page:
          type:
            - integer
            - 'null'
          description: The next page number (null if on last page)
          example: 3
        prev_page:
          type:
            - integer
            - 'null'
          description: The previous page number (null if on first page)
          example: 1
        total_pages:
          type: integer
          description: Total number of pages
          example: 11
        total_count:
          type: integer
          description: Total number of items across all pages
          example: 210
        per_page:
          type: integer
          description: Number of items per page
          example: 20
    UnprocessableEntityError:
      type: object
      properties:
        status:
          type: string
          example: unprocessable entity
        code:
          type: string
          description: Error code.
          example: missing_key
        detail:
          type: string
          description: Human readable error that explains error `code`.
          example: property is missing
        message:
          type: string
          example: property id is missing
        source:
          type: object
          properties:
            pointer:
              type: string
              description: >-
                The property and the item in an array (if applicable) that
                causes the error.
              example: id
      required:
        - code
        - detail
      x-examples:
        Missing property:
          code: missing_key
          detail: property is missing
          source:
            pointer: /external_transfer/atrribute
    BadRequestResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BadRequestError'
      required:
        - errors
    UnauthorizedResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/UnauthorizedError'
      required:
        - errors
    ForbiddenResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ForbiddenError'
      required:
        - errors
    BadRequestError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
        source:
          type: object
          properties:
            pointer:
              type: string
              description: >-
                The property in the request body that caused the error
                (optional).
            parameter:
              type: string
              description: The query parameter that caused the error (optional).
      required:
        - code
        - detail
      x-examples:
        Authorization field missing:
          code: bad_request
          detail: Authorization field missing
    UnauthorizedError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Invalid credentials:
          code: unauthorized
          detail: Invalid credentials
    ForbiddenError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Insufficient permissions:
          code: forbidden
          detail: User does not have sufficient permissions for this action.
  responses:
    400-Bad-request:
      description: Returns a bad request error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestResponseBody'
          examples:
            Authorization field missing:
              value:
                errors:
                  - code: bad_request
                    detail: Authorization field missing
    401-Unauthorized:
      description: Returns an unauthorized error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponseBody'
          examples:
            authorization_header_missing:
              value:
                errors:
                  - code: authorization_header_missing
                    detail: authorization header missing
            authorization_token_invalid:
              value:
                errors:
                  - code: authorization_token_invalid
                    detail: authorization token invalid
    403-Forbidden:
      description: Returns a forbidden error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenResponseBody'
          examples:
            Insufficient permissions:
              value:
                errors:
                  - code: forbidden
                    detail: User does not have sufficient permissions for this action.
    500-Internal-Server-Error:
      description: Returns an internal server error.
  securitySchemes:
    OAuth:
      type: oauth2
      description: >
        Bearer authorization header: `Bearer <token>`, where `<token>` is the
        access token received from the authorization server at the end of the
        [OAuth 2.0
        flow](/get-started/business-api/authentication/oauth/oauth-flow).
      flows:
        authorizationCode:
          refreshUrl: https://oauth.qonto.com/oauth2/token
          authorizationUrl: https://oauth.qonto.com/oauth2/auth
          scopes:
            attachment.read: Retrieve attachments
            attachment.write: Upload attachments and remove attachments from transactions
            bank_account.write: Create, update and close bank accounts
            beneficiary.trust: Trust SEPA beneficiaries
            card.read: Retrieve cards
            card.write: Create or update cards
            client.read: Retrieve clients
            client.write: Create clients
            client_invoice.write: Create client invoices
            client_invoices.read: Retrieve client invoices and credit notes
            einvoicing.read: Retrieve e-invoicing settings
            embed_auth_link.write: Create Embed auth links
            insurance_contract.read: Retrieve insurance contracts
            insurance_contract.write: Create and update insurance contracts
            internal_transfer.write: >-
              Create internal transfers (between 2 Qonto accounts of the same
              organization)
            international_transfer.write: Create international transfers
            membership.read: Retrieve the authentified membership
            membership.write: Invite team members
            offline_access: Retrieve a refresh token
            organization.read: >-
              Retrieve organization, bank accounts, transactions, transfers,
              beneficiaries, labels, memberships, requests & statements
            payment.write: Create external transfers and untrust beneficiaries
            payment_link.read: >-
              Retrieve payment links, their payments, and the available payment
              methods
            payment_link.write: >-
              Connect to the payment links provider, create and deactivate
              payment links
            product.read: Retrieve products
            product.write: Create products
            request_cards.write: Create card requests
            request_review.write: Approve or decline requests
            request_transfers.write: Create transfer requests
            sepa_direct_debit.read: View SEPA Direct Debit payments
            sepa_direct_debit.write: Manage SEPA Direct Debit payments
            supplier_invoice.read: Retrieve supplier invoices
            supplier_invoice.write: Create supplier invoices
            team.read: Retrieve teams
            team.write: Create teams
            terminal.read: View your payment terminals
            terminal.write: Configure your terminals and initiate payments
            webhook: >-
              Receive a notification each time a particular event occurs in
              Qonto
          tokenUrl: https://oauth.qonto.com/oauth2/token
    SecretKey:
      type: apiKey
      description: cf. [API key](/get-started/business-api/authentication/api-key)
      name: Authorization
      in: header

````