Belvo Consents API

openapi: 3.2.0
info:
  title: Belvo API Docs Consents API
  version: 1.223.0
  description: '# Introduction


    Reach new audiences and convert more users by easily and safely connecting to their financial data, understanding their behavior and enabling instant payments with open finance. Through our API, you can access:


    ## Available Information and Payment Methods


    Belvo is an open banking API for Latin America that allows companies to access banking and fiscal information in a secure as well as agile way. Through our API, you can access:


    - Banking Information in Brazil

    - Employment Information in Brazil

    - Employment Information in Mexico

    - Fiscal Information in Mexico

    - Fiscal Information in Chile


    You can also use our API to make payments in:


    - Brazil

    - Mexico


    ## Data Dictionaries


    If you woud like the response documentation in Excel or CSV form, please download them from our public GitHub Reposiitory: Belvo Open Finance Data Dictionaries. Our EXCEL and CSV files are additionally localized into Spanish and Portuguese (Brazil). ## Environments


    We currently offer two environments: sandbox and production. ### Sandbox


    Available for:


    - 🟢 Aggregation and Enrichment

    - ⚪️ Payment Initiation


    Use our Sandbox environment to build your integration. We offer dummy data that mimics that of real-world use cases, which means you can test out all the endpoints, use the widget, and implement webhooks - just as you would with real-world data! All you need to get started with the Sandbox environment is to get your API keys. We really recommend that you start creating your integration in this environment. ### Production


    Available for:


    - 🟢 Aggregation and Enrichment

    - 🟢 Payment Initiation


    After you have tested your integration in the Sandbox environment and are ready to go live, you''ll need to request access to our Production environment. After you request access, our Sales Team will get in contact with you to schedule a meeting just to ensure your needs are met, and then you''ll just need to go through a certification process with one of our engineers to make sure that your integration is running optimally. To prepare for the certification meeting, just follow our Integration checklist. Once your integration is certified, all you''ll need to do is:


    - [ ] Request Production API keys (and change your Sandbox API keys in the code to these new ones). - [ ] Change the base URL that you make requests to from `sandbox.belvo.com` to `api.belvo.com`. - [ ] If you''re using webhooks, make sure to set a Production URL for your webhooks. ## Response codes


    We use the following HTTP status code in the response depending on the

    success or failure:


    | Status Code | Description |

    |-----------|-------|

    | `200` | ✅ **Success** - The content is available in the response body. |

    | `201` | ✅ **Success** - The content was created successfully on Belvo. |

    | `204` | ✅ **Success** - No content to return. |

    | `400` | ❌ **Bad Request Error** - Request returned an error, detail in the content.|

    | `401` | ❌ **Unauthorized** - The Belvo credentials provided are not valid.|

    | `404` | ❌ **Not Found** - The resource you try to access cannot be found.|

    | `405` | ❌ **Method Not Allowed** - The HTTP method you are using is not accepted for this resource.|

    | `408` | ❌ **Request Timeout** - The request timed out and was terminated by the server.|

    | `428` | ❌ **MFA Token Required** - MFA token was required by the institution to connect. |

    | `500` | ❌ **Internal Server Error** - The detail of the error is available in the response body.|


    ## Error handling


    Belvo API errors are returned in JSON format. For example, an error might look like this:


    ```json

    [

    {

    "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",

    "message": "This field is required.",

    "code": "required",

    "field": "link"

    }

    ]

    ```


    Typically, an error response will have the following parameters:


    - `request_id`: a unique ID for the request, you should share it with the Belvo support team for investigations. - `message`: human-readable description of the error. - `code`: a unique code for the error.'
  contact:
    name: Need help?
    url: https://developers.belvo.com
    email: support@belvo.com
  x-logo:
    url: https://files.readme.io/5111448-belvo-for-developers.svg
    altText: Belvo Logo
servers:
- url: https://sandbox.belvo.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Consents
  description: A consent is a permission given by the end user to access their financial data in the Open Finance Network in Brazil.
paths:
  /api/consents/:
    get:
      tags:
      - Consents
      operationId: ListConsents
      summary: List consents
      description: '## ▶️ 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.'
      parameters:
      - $ref: '#/components/parameters/pageSize_query'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/omit'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/document_number'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/common_pagination_properties'
                - properties:
                    results:
                      type: array
                      description: Array of consent objects.
                      items:
                        $ref: '#/components/schemas/Consents'
        '401':
          $ref: '#/components/responses/401_unauthorized_error'
        '403':
          $ref: '#/components/responses/403_access_denied_error'
        '404':
          $ref: '#/components/responses/404_not_found_error'
        '408':
          $ref: '#/components/responses/408_request_timeout_error'
        '500':
          $ref: '#/components/responses/500_unexpected_error'
  /api/consents/{id}/:
    get:
      tags:
      - Consents
      operationId: DetailConsent
      summary: Get a consent's details
      description: Get the details of a specific consent.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The `consent.id` you want to get detailed information about.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Consents'
        '401':
          $ref: '#/components/responses/401_unauthorized_error'
        '403':
          $ref: '#/components/responses/403_access_denied_error'
        '404':
          $ref: '#/components/responses/404_not_found_error'
        '408':
          $ref: '#/components/responses/408_request_timeout_error'
        '500':
          $ref: '#/components/responses/500_unexpected_error'
components:
  parameters:
    fields:
      name: fields
      in: query
      description: Return only the specified fields in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.
      schema:
        type: string
    omit:
      name: omit
      in: query
      description: Omit certain fields from being returned in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.
      schema:
        type: string
    page:
      name: page
      in: query
      description: A page number within the paginated result set.
      schema:
        type: integer
        format: int32
        minimum: 1
        example: 1
    document_number:
      name: user_document
      required: true
      in: query
      description: 'The CPF or CNPJ number of the user you want to get consent information for.

        '
      schema:
        type: string
        minLength: 11
        maxLength: 14
        example: '12345678900'
    pageSize_query:
      name: page_size
      in: query
      description: "Indicates how many results to return per page. By default we return 100 results per page. \n\nℹ️ 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).\n"
      schema:
        type: integer
        format: int32
        default: 100
        minimum: 1
        maximum: 1000
        example: 100
  responses:
    408_request_timeout_error:
      description: Request Timeout
      content:
        application/json:
          schema:
            type: array
            title: Request Timeout
            description: "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n  \n"
            items:
              $ref: '#/components/schemas/RequestTimeoutError'
    403_access_denied_error:
      description: Access to Belvo API denied
      content:
        application/json:
          schema:
            type: array
            description: 'This error occurs when you try to access Belvo''s resource without the correct permissions.

              '
            items:
              $ref: '#/components/schemas/AccessToResourceDenied'
    401_unauthorized_error:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: array
            items:
              anyOf:
              - $ref: '#/components/schemas/UnauthorizedError'
              - $ref: '#/components/schemas/ConsentWithoutAccountsError'
    404_not_found_error:
      description: Not Found Error
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NotFoundError'
    500_unexpected_error:
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: array
            title: Unexpected Error
            description: "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n  \n"
            items:
              $ref: '#/components/schemas/UnexpectedError'
  schemas:
    request_id:
      type: string
      pattern: '[a-f0-9]{32}'
      description: '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
    ConsentWithoutAccountsError:
      type: object
      title: Consent Without Accounts
      description: 'This error occurs when your user has removed accounts associated with the consent they provided. For example, when your user first generated their consent, they had a checking and a loan account at the institution but has closed those accounts since then.

        '
      properties:
        code:
          type: string
          description: 'A unique error code (`consent_without_accounts`) that allows you to classify and handle the error programmatically.



            ℹ️ Check our DevPortal for more information on how to handle <a href="https://developers.belvo.com/docs/belvo-api-errors#401-consent_without_accounts" target="_blank">401 consent_without_accounts errors</a>.

            '
          example: consent_without_accounts
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `invalid` errors relating to `fetch_resources`, the description is:\n  \n  - `The institution only supports the following resources: (comma-separated list of supported resources)`.\n"
          example: 'The institution only supports the following resources: EMPLOYMENT_RECORDS, OWNERS'
        request_id:
          $ref: '#/components/schemas/request_id'
    EnumConsentStatus:
      type:
      - string
      - 'null'
      enum:
      - AUTHORISED
      - AWAITING_AUTHORISATION_CONFIRMATION
      - AWAITING_AUTHORISATION
      - REJECTED
      - EXPIRED
      - null
      description: "The status of the consent in the open finance network. Can be either:\n\n  - `AUTHORISED`: The consent is still valid for use until the `expired_at` date.\n  - `AWAITING_AUTHORISATION_CONFIRMATION`: The user must confirm within their institution.\n  - `AWAITING_AUTHORISATION`: The user has been redirected to their institution to grant consent.\n  - `REJECTED`: The user has not granted consent within their institution.\n  - `EXPIRED`: The consent has expired as of the `expired_at` date.\n  - `null`\n"
      example: AUTHORISED
    UnauthorizedError:
      type: object
      title: Unauthorized Error
      description: 'This error occurs when you try to make an API call using incorrect Belvo API credentials (either your secret key or secret password, or both, are incorrect).

        '
      properties:
        code:
          type: string
          description: 'A unique error code (`authentication_failed`) that allows you to classify and handle the error programmatically.



            ℹ️ Check our DevPortal for more information on how to handle <a href="https://developers.belvo.com/docs/belvo-api-errors#401-authentication_failed" target="_blank">401 authentication_failed errors</a>.

            '
          example: authentication_failed
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `authentication_failed` errors, the description is:\n\n  - `Invalid Secret Keys`.\n"
          example: Invalid Secret Keys
        request_id:
          $ref: '#/components/schemas/request_id'
    created_at:
      type: string
      format: date-time
      description: 'The ISO-8601 timestamp of when the data point was created in Belvo''s database.

        '
      example: '2022-02-09T08:45:50.406032Z'
    Consents:
      type: object
      description: The OFDA consents schema
      title: Consents Object (Brazil)
      x-tags:
      - Consents
      properties:
        id:
          $ref: '#/components/schemas/id'
        display_name:
          type:
          - string
          - 'null'
          maxLength: 128
          pattern: ^[\w\W]{0,128}$
          description: 'The full name of the individual that initiated the consent, as provided by the institution.

            '
          example: Jack Oswald White
        document_number:
          type: string
          description: 'The document number (CPF) of the individual.

            '
          example: '76109277673'
        belvo_institution_name:
          type: string
          description: 'Belvo''s name for the open finance institution that the consent is related to.

            '
          example: ofmockbank_br_retail
        institution_display_name:
          type: string
          description: 'The display name of the banking institution that the consent is related to.

            '
          example: Mock Bank
        institution_icon_logo:
          type: string
          description: 'The URL to the banking institution''s logo.

            '
          example: https://assets.belvo.io/institutions/mockbank/logo.svg
        belvo_organization_name:
          type: string
          description: 'The name registered in Belvo of the organization that created the link.

            '
          example: ACME Corporation
        link_id:
          type: string
          format: uuid
          description: 'The Belvo link ID that the consent belongs to.

            '
          example: 2e5d2c5e-6b3a-4b5c-8d1e-9f0a1b2c3d4e
        user_name:
          type:
          - string
          - 'null'
          description: 'The name provided in `consent.identification_info.name` during the initial Widget Access Token Request.

            '
          example: Jack White
        expired_at:
          type: string
          format: date-time
          description: 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'
        undefined_consent_expiration:
          type: boolean
          description: Indicated whether the consent is for an undefined period, that is, that there is no expiration for the consent.
          example: false
        consent_duration:
          type:
          - integer
          - 'null'
          description: '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
        created_at:
          $ref: '#/components/schemas/created_at'
        status:
          $ref: '#/components/schemas/EnumConsentStatus'
        permissions:
          type: object
          description: Details regarding the permissions attached to the consent.
          properties:
            ACCOUNTS:
              type: array
              description: A list of of open banking permissions relating to accessing account information.
              items:
                type: string
                example: ACCOUNTS_OVERDRAFT_LIMITS_READ
              example:
              - ACCOUNTS_OVERDRAFT_LIMITS_READ
              - ACCOUNTS_READ
              - ACCOUNTS_TRANSACTIONS_READ
              - ACCOUNTS_BALANCES_READ
            CREDIT_CARDS:
              type: array
              description: A list of of open banking permissions relating to accessing credit card information.
              items:
                type: string
                example: CREDIT_CARDS_ACCOUNTS_LIMITS_READ
              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
            CREDIT_OPERATIONS:
              type: array
              description: A list of of open banking permissions relating to accessing credit product information.
              items:
                type: string
                example: LOANS_READ
              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
            REGISTER:
              type: array
              description: A list of of open banking permissions relating to accessing personal information.
              items:
                type: string
                example: CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ
              example:
              - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ
              - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
            RESOURCES:
              type: array
              description: A list of functional permissions required to interact with the permissions.
              items:
                type: string
                example: RESOURCES_READ
              example:
              - RESOURCES_READ
            INVESTMENTS:
              type: array
              description: A list of open banking permissions relating to accessing investment information.
              items:
                type: string
                example: BANK_FIXED_INCOMES_READ
              example:
              - BANK_FIXED_INCOMES_READ
              - CREDIT_FIXED_INCOMES_READ
              - FUNDS_READ
              - VARIABLE_INCOMES_READ
              - TREASURE_TITLES_READ
    id:
      type: string
      format: uuid
      description: 'Belvo''s unique identifier for the current item.

        '
      example: 0d3ffb69-f83b-456e-ad8e-208d0998d71d
    AccessToResourceDenied:
      type: object
      title: Access to Belvo API denied
      description: 'This error occurs when you try to access Belvo''s resource without the correct permissions.

        '
      properties:
        code:
          type: string
          description: '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 <a href="https://developers.belvo.com/docs/belvo-api-errors#403-access_to_resource_denied" target="_blank">403 access_to_resource_denied</a>.

            '
          example: access_to_resource_denied
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `access_to_resource_denied` errors, the description is:\n  \n  - `You don't have access to this resource.`.\n"
          example: You don't have access to this resource.
        request_id:
          $ref: '#/components/schemas/request_id'
    UnexpectedError:
      type: object
      title: Unexpected Error
      description: 'This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.

        '
      properties:
        code:
          type: string
          description: '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 <a href="https://developers.belvo.com/docs/belvo-api-errors#500-unexpected_error" target="_blank">500 unexpected_error errors</a>.

            '
          example: unexpected_error
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `unexpected_error` errors, the description is:\n  \n  - `Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution`.\n"
          example: Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution
        request_id:
          $ref: '#/components/schemas/request_id'
    NotFoundError:
      type: object
      title: Not Found
      properties:
        code:
          type: string
          description: 'A unique error code (`not_found`) that allows you to classify and handle the error programmatically.

            '
          example: not_found
        message:
          type: string
          description: "A short description of the error.\n\n\nFor `not_found` errors, the description is:\n\n  - `Not found`\n"
          example: Not found
        request_id:
          $ref: '#/components/schemas/request_id'
    RequestTimeoutError:
      type: object
      title: Request Timeout
      description: 'Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.

        '
      properties:
        code:
          type: string
          description: '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 <a href="https://developers.belvo.com/docs/belvo-api-errors#408-request_timeout" target="_blank">408 request_timeout errors</a>.

            '
          example: request_timeout
        message:
          type: string
          description: "A short description of the error. \n\n\nFor `request_timeout` errors, the description is:\n  \n  - `The request timed out, you can retry asking for less data by changing your query parameters`.\n"
          example: The request timed out, you can retry asking for less data by changing your query parameters
        request_id:
          $ref: '#/components/schemas/request_id'
    common_pagination_properties:
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: The total number of results in your Belvo account.
          example: 130
        next:
          type:
          - string
          - 'null'
          format: uri
          description: '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-34d1044cb908&page=2
        previous:
          type:
          - string
          - 'null'
          format: uri
          description: 'The URL to the previous page of results. If there is no previous page, the

            value is `null`.

            '
          example: null
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: "Belvo employs **basic authentication** using your secret keys (You can find your API secret keys in your Belvo Dashboard, under the **Developers** section).\n\n\nTo authenticate, you need to use your API `secretId` as the `username` and your API `secretPassword` as the `password`. These credentials need to be **Base64 encoded** and included in the `Authorization` header of your HTTP requests. For example:\n\n\n```shell\ncurl -X GET https://sandbox.belvo.com/api/ \\\n  -H \"Authorization: Basic $(echo -n 'YOUR_SECRET_ID:YOUR_SECRET_PASSWORD' | base64)\"\n```\n\nReplace `YOUR_SECRET_ID` and `YOUR_SECRET_PASSWORD` with your actual credentials. **Never expose your credentials in client-side code or public repositories**."
x-tagGroups:
- name: Core Resources
  tags:
  - Institutions
  - Links
  - Widget Access Token
  - Consents
- name: Open Finance Data Aggregation (Brazil)
  tags:
  - Owners
  - Accounts
  - Balances
  - Exchanges
  - Transactions
  - Bills
  - Investments Brazil
  - Investment Transactions Brazil
- name: Employments Brazil
  tags:
  - Employments Brazil
- name: Employment Records Mexico
  tags:
  - Employment Records Mexico
  - Current Employments Mexico
- name: Fiscal Mexico
  tags:
  - Invoices
  - Tax compliance status
  - Tax returns
  - Tax retentions
  - Tax status
  - Financial Statements
- name: Fiscal Chile
  tags:
  - Invoices Chile
  - Tax Status Chile
  - Debt Reports Chile
- name: Enrichment API
  tags:
  - Incomes
  - Recurring Expenses
  - Risk Insights
  - Employment Metrics
- name: Payment Initiation (Brazil)
  tags:
  - Payment Initiation introduction (Brazil)
  - Payment Institutions (Brazil)
  - Customers (Brazil)
  - Bank Accounts (Brazil)
  - Payment Authorizations (Brazil)
  - Charges (Brazil)
  - Payment Intents (Brazil)
  - Biometric payments Widget Access Token (Brazil)
  - Enrollments (Brazil)
  - Payment Transactions (Brazil)
x-provenance:
  method: harvested
  publisher: Belvo
  source: https://developers.belvo.com/_bundle/apis/BelvoOpenApiSpec.json?download
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)