# List links

## ▶️ Usage

With the List Links method, you can:

1. List all links elated to your Belvo account (without using any query parameters).
2. Get the details of a specific link.id (using the id query parameter).

## 📖 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/links/
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.

  - `id` (string)
    Return information only for this resource id.
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `id__in` (array)
    Return information for these resource ids.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `institution` (string)
    Return results only for this institution (use the Belvo-designated name, such as planet_mx_employment).
    Example: "planet_mx_retail"

  - `institution__in` (array)
    Return results only for these institutions (use the Belvo-designated names, such as ofmockbank_br_retail and planet_mx_employment).
    Example: ["planet_mx_retail"]

  - `access_mode` (string)
    Return links only with this access mode. Can be either single or recurrent.
    Enum: "single", "recurrent"

  - `created_at` (string)
    Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

  - `created_by__not_in` (array)
    Return links that were not created by these Belvo users.
    Example: ["d9475f4d-c511-4732-9ef0-93b5672f43d3"]

  - `external_id` (string)
    Return links with this external ID.
    Example: "InternalUser4000"

  - `external_id__in` (array)
    Return links with these external IDs.
    Example: ["InternalUser4001"]

  - `institution_user_id` (string)
    Return links with this specific institution user ID.
    Example: "ezFoxjPDr7YnASnOaft5F3zt7D0kurgDNlLtZFjxUo0="

  - `institution_user_id__in` (array)
    Return links with these institution user IDs.
    Example: ["ezFoxjPDr7YnASnOaft5F3zt7D0kurgDNlLtZFjxUo0="]

  - `refresh_rate` (string)
    Return links with this refresh rate. Choose between 6h, 12h, 24h, 7d, 30d, or null (for single links).
    Example: "24h"

  - `status` (string)
    Return links with this status. Choose between valid, invalid, unconfirmed, or token_required.
    Example: "invalid"

  - `status__in` (array)
    Return links with these statuses. Choose between valid, invalid, unconfirmed, or token_required.
    Example: ["invalid"]

## 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 link objects.

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

  - `results.institution` (string)
    Belvo's name for the institution.
    Example: "erebor_mx_retail"

  - `results.access_mode` (string,null)
    The link type.
For more information, see our Links article.
We return one of the following enum values:
  - single
  - recurrent
  - null
    Enum: "single", "recurrent", null

  - `results.last_accessed_at` (string,null)
    The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.
    Example: "2021-03-09T10:28:40.000Z"

  - `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.external_id` (string)
    An additional identifier for the link, provided by you, to store in the Belvo database. Cannot include any Personal Identifiable Information (PII). Must be at least three characters long.


If we identify that the identifier contains PII, we will force a null value. For more information, see our Link creation article.
    Example: "56ab5706-6e00-48a4-91c9-ca55968678d9"

  - `results.institution_user_id` (string)
    > 📘 Info
>
> Only applicable for links created after 08-02-2022.


A unique 44-character string that can be used to identify a user at a given institution.


📚 Check out our Avoiding duplicated links DevPortal article for more information and tips on how to use it.
    Example: "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="

  - `results.status` (string)
    The current status of the link. For more information, see our Link article in the devportal.
We return one of the following values:
  - valid
  - invalid
  - unconfirmed
  - token_required
    Enum: "valid", "invalid", "unconfirmed", "token_required"

  - `results.created_by` (string)
    The unique ID for the user that created this item.
    Example: "bcef7f35-67f2-4b19-b009-cb38795faf09"

  - `results.refresh_rate` (string,null)
    The update refresh rate for the recurrent link. For more information, check out our recurrent link documentation in our DevPortal.
We return one of the following enum values:
  - 6h
  - 12h
  - 24h
  - 7d (default)
  - 30d (once a month)
  - null (for single links)
    Enum: "6h", "12h", "24h", "7d", "30d", null

  - `results.credentials_storage` (string)
    Indicates whether or not to store credentials (and the duration for which to store the credentials).

- For recurrent links, this is set to store by default (and cannot be changed). 
- For single links, this is set to 365d by default.

Can be either:
  - store to store credentials (until the link is deleted)
  - nostore to not store credentials
  -  Any value between 1d and 365d to indicate the number of days you want the credentials to be stored.

 For more information, check out the credentials_storage section of our Data retention controls article.
    Example: "27d"

  - `results.fetch_resources` (array)
    An array of resources that you will receive a historical update for.
    Example: ["ACCOUNTS","TRANSACTIONS"]

  - `results.stale_in` (string)
    Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through 90d, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article.

> 📘 Info
>
> Belvo will only remove data for links that have not been updated in the period you provide in stale_in. Belvo will only remove data for links that have not been updated in the period you provide in stale_in.

By default Belvo stores user data for 365 days, unless the link is deleted.
    Example: "42d"

## 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 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"