# List consents

## ▶️ Usage

With the Consents method, you can:

1. List all consents related to your Belvo account (without using any query parameters).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

Endpoint: GET /api/consents/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page. 

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `omit` (string)
    Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

  - `fields` (string)
    Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

  - `user_document` (string, required)
    The CPF or CNPJ number of the user you want to get consent information for.
    Example: "12345678900"

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of consent objects.

  - `results.id` (string)
    Belvo's unique identifier for the current item.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `results.display_name` (string,null)
    The full name of the individual that initiated the consent, as provided by the institution.
    Example: "Jack Oswald White"

  - `results.document_number` (string)
    The document number (CPF) of the individual.
    Example: "76109277673"

  - `results.belvo_institution_name` (string)
    Belvo's name for the open finance institution that the consent is related to.
    Example: "ofmockbank_br_retail"

  - `results.institution_display_name` (string)
    The display name of the banking institution that the consent is related to.
    Example: "Mock Bank"

  - `results.institution_icon_logo` (string)
    The URL to the banking institution's logo.
    Example: "https://assets.belvo.io/institutions/mockbank/logo.svg"

  - `results.belvo_organization_name` (string)
    The name registered in Belvo of the organization that created the link.
    Example: "ACME Corporation"

  - `results.link_id` (string)
    The Belvo link ID that the consent belongs to.
    Example: "2e5d2c5e-6b3a-4b5c-8d1e-9f0a1b2c3d4e"

  - `results.user_name` (string,null)
    The name provided in consent.identification_info.name during the initial Widget Access Token Request.
    Example: "Jack White"

  - `results.expired_at` (string)
    The ISO-8601 timestamp when the consent will expire. In the case that undefined_consent_expiration is true, this field will be null.
    Example: "2021-02-27T13:01:41.941Z"

  - `results.undefined_consent_expiration` (boolean)
    Indicated whether the consent is for an undefined period, that is, that there is no expiration for the consent.

  - `results.consent_duration` (integer,null)
    The duration of the consent in days. In the case that undefined_consent_expiration is true, this field will be null.

Possible values:
- 92 (3 months)
- 183 (6 months)
- 275 (9 months)
- 366 (12 months)
    Example: 366

  - `results.created_at` (string)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `results.status` (string,null)
    The status of the consent in the open finance network. Can be either:

  - AUTHORISED: The consent is still valid for use until the expired_at date.
  - AWAITING_AUTHORISATION_CONFIRMATION: The user must confirm within their institution.
  - AWAITING_AUTHORISATION: The user has been redirected to their institution to grant consent.
  - REJECTED: The user has not granted consent within their institution.
  - EXPIRED: The consent has expired as of the expired_at date.
  - null
    Enum: "AUTHORISED", "AWAITING_AUTHORISATION_CONFIRMATION", "AWAITING_AUTHORISATION", "REJECTED", "EXPIRED", null

  - `results.permissions` (object)
    Details regarding the permissions attached to the consent.

  - `results.permissions.ACCOUNTS` (array)
    A list of of open banking permissions relating to accessing account information.
    Example: ["ACCOUNTS_OVERDRAFT_LIMITS_READ","ACCOUNTS_READ","ACCOUNTS_TRANSACTIONS_READ","ACCOUNTS_BALANCES_READ"]

  - `results.permissions.CREDIT_CARDS` (array)
    A list of of open banking permissions relating to accessing credit card information.
    Example: ["CREDIT_CARDS_ACCOUNTS_LIMITS_READ","CREDIT_CARDS_ACCOUNTS_BILLS_READ","CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ","CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ","CREDIT_CARDS_ACCOUNTS_READ"]

  - `results.permissions.CREDIT_OPERATIONS` (array)
    A list of of open banking permissions relating to accessing credit product information.
    Example: ["LOANS_READ","LOANS_WARRANTIES_READ","LOANS_SCHEDULED_INSTALMENTS_READ","LOANS_PAYMENTS_READ","FINANCINGS_READ","FINANCINGS_WARRANTIES_READ","FINANCINGS_SCHEDULED_INSTALMENTS_READ","FINANCINGS_PAYMENTS_READ","UNARRANGED_ACCOUNTS_OVERDRAFT_READ","UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ","UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ","UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ","INVOICE_FINANCINGS_READ","INVOICE_FINANCINGS_WARRANTIES_READ","INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ","INVOICE_FINANCINGS_PAYMENTS_READ"]

  - `results.permissions.REGISTER` (array)
    A list of of open banking permissions relating to accessing personal information.
    Example: ["CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ","CUSTOMERS_PERSONAL_ADITTIONALINFO_READ"]

  - `results.permissions.RESOURCES` (array)
    A list of functional permissions required to interact with the permissions.
    Example: ["RESOURCES_READ"]

  - `results.permissions.INVESTMENTS` (array)
    A list of open banking permissions relating to accessing investment information.
    Example: ["BANK_FIXED_INCOMES_READ","CREDIT_FIXED_INCOMES_READ","FUNDS_READ","VARIABLE_INCOMES_READ","TREASURE_TITLES_READ"]

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"