# Belvo API Docs # 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. Check the table below to see how to handle each error code. - `field` *(optional)*: The specific field in the request body that has an issue. ### Request identifier When you need help with a specific error, include the request identifier (`request_id`) in your message to the Belvo support team. This will speed up investigations and get you back up and running in no time at all. ### Error codes and troubleshooting For a full list of errors and how to troubleshoot them, please see our dedicated Error Handling article. ### Retry policy #### 50x errors Implement an automated exponential backoff of up to five retries. We recommend using a base interval of three seconds with a factor of two. For example, the first retry should be after three seconds, the second retry after six seconds (2 * 3), the third retry after 12 seconds (2 * 6), the fourth retry after 24 seconds (2 * 12), and the fifth retry after 48 seconds (2 * 24). #### 40x errors You should not retry making requests if you receive a 40x response, as this is a client error. The only exception is the β€œToo Many Sessions” error, as it means that your end-user is accessing the account from another browser at the same time. In this case, please implement the same retry policy as with 50x errors. ## Deprecated fields In our schema, you may see that a field has been marked as `deprecated`. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should **not** rely on this field. ## OpenAPI: required and nullable fields In our API specification, you'll see that some response parameters will have a **required** annotation. According to the OpenAPI specification, when a response parameter is marked as **required**, this means that the response key must be returned. However, the value of that response parameter can be `null`. > πŸ“˜ Info > > In short, any response parameter marked as required will be returned by our API, but the value can be set to null. Version: 1.223.0 ## Servers Sandbox ``` https://sandbox.belvo.com ``` ## Security ### basicAuth Belvo employs **basic authentication** using your secret keys (You can find your API secret keys in your Belvo Dashboard, under the **Developers** section). To 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: ```shell curl -X GET https://sandbox.belvo.com/api/ \ -H "Authorization: Basic $(echo -n 'YOUR_SECRET_ID:YOUR_SECRET_PASSWORD' | base64)" ``` Replace `YOUR_SECRET_ID` and `YOUR_SECRET_PASSWORD` with your actual credentials. **Never expose your credentials in client-side code or public repositories**. Type: http Scheme: basic ## Download OpenAPI description [Belvo API Docs](https://developers.belvo.com/_bundle/apis/BelvoOpenApiSpec.yaml) ## Institutions An **institution** is an entity that Belvo can access information from. It can be a: - bank institution, such as Nubank Brazil. - fiscal institution, such as the *Servicio de AdministraciΓ³n Tributaria (SAT)* in Mexico. - employment institutions, such as *Instituto Mexicano del Seguro Social (IMSS)* in Mexico or *Instituto Nacional do Seguro Social (INSS)* in Brazil. ### List institutions - [GET /api/institutions/](https://developers.belvo.com/apis/belvoopenapispec/institutions/listinstitutions.md): ## ▢️ Usage With the List Institutions method, you can: 1. List all institutions Belvo has available. ## πŸ“– 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. ### Get an institution's details - [GET /api/institutions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/institutions/detailinstitution.md): Get the details of a specific institution. ## Links A **Link** is a set of credentials associated to an end-user's access to an **institution**. You will need to register a **Link** before accessing information from that specific end-user, such as account or transaction details. We recommend using the Belvo Hosted Widget to manage the connection process. ### List links - [GET /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/listlinks.md): ## ▢️ 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. ### Register a new link - [POST /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/registerlink.md): ## ▢️ Usage Register a new link (a connection between your user and their institution) using the Belvo API. > πŸ‘ We really recommend using our Connect Widget to handle link creation and link status updates. To make things easier, we've included custom examples for the links you can create for each of our products. Just click on the type of link you want to create in the Body Params section below. ### Complete a links request - [PATCH /api/links/](https://developers.belvo.com/apis/belvoopenapispec/links/patchlinks.md): Used to resume a Link register session that was paused because an MFA token was required by the institution. ### Get a link's details - [GET /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/detaillink.md): Get the details of a specific link. ### Modify a link's data retrieval - [PATCH /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/modifylinkdataretrieval.md): Modify the data retrieval settings for a specific link. At present you can: - Change a link's access mode from single to recurrent or from recurrent to single. - Modify they stale_in period for the link. - Modify the historical resources you want to retrieve for the link (fetch_resources). ## Changing a link's access_mode When you change a link from single to recurrent, the next day a historical update of the core resources for the link is triggered (resulting in you receiving historical_update webhooks for the link). You are billed for these historical updates. ## Modifying stale_in If you only modify the stale_in period for a link, this will not trigger a historical update. In order to trigger a historical update for the link, you must change the access_mode. ## Modifying fetch_resources If you only modify the fetch_resources for a link, this will not trigger a historical update. In order to trigger a historical update for the link, you must change the access_mode. ### Update a link's credentials - [PUT /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/updatelink.md): Update the credentials of a specific link. If the successfully updated link is a recurrent one, we automatically trigger an update of the link. If we find fresh data, you'll receive historical update webhooks. > πŸ‘ Use our Connect Widget > > We recommend using our Connect Widget to handle updating invalid or token_required links. ### Delete a link - [DELETE /api/links/{id}/](https://developers.belvo.com/apis/belvoopenapispec/links/destroylink.md): Delete a specific link and all the associated data (for example: transactions, accounts, invoices, tax returns, employments, and so on) for that link from your Belvo account. This action is irreversible, and you will not be able to recover the deleted data. {% admonition type="success" name="Use the X-Belvo-Request-Mode: async header" %} We highly recommend setting the X-Belvo-Request-Mode header to async to enable asynchronous deletion. This way, you will avoid the rate limit of 5 deletions per minute. When set, the endpoint will respond with a 202 Accepted status and provide a request ID for tracking the deletion process. Once the process is complete, you will receive a link_deleted webhook notification. If you do not set this header, the endpoint will respond with a 204 No Content status, but you will be subject to the rate limit of 5 deletions per minute. If you exceed this limit, you will receive a 429 Too Many Requests error. {% /admonition %} ### Trigger a historical update for a link - [POST /api/links/{id}/refresh/](https://developers.belvo.com/apis/belvoopenapispec/links/refreshhistoricaldataforlink.md): {% admonition type="warning" name="Concurrent Request Limit" %} To prevent duplicate requests, this endpoint has a 10-minute cooldown period per link. If you attempt to refresh the same link within 10 minutes of a previous request, you will receive a 409 Conflict error with the message "The link has already been refreshed. Please wait X minutes before trying again.". {% /admonition %} Use this method to trigger a historical update for a specific link (single or recurrent). Use the fetch_resources parameter to specify which resources you want to update. If you do not specify this parameter, the historical update will be performed for all resources supported by the institution that the link is associated with. On a successful request, our API will respond with a 202 status code and a request_id that you can later use to associate a given historical_update webhook to this request. {% admonition type="info" name="Does not update link definition" %} This endpoint does not update the link definition itself, only the historical data for the specified resources. If you want to change the link's fetch_resources permanently, you should use the Modify a link's data retrieval method instead. {% /admonition %} ## Widget Access Token ### Generate a widget access token - [POST /api/token/](https://developers.belvo.com/apis/belvoopenapispec/widget-access-token/generatewidgetaccesstoken.md): Generate a widget access token for our Hosted Widget. ## Consents A consent is a permission given by the end user to access their financial data in the Open Finance Network in Brazil. ### List consents - [GET /api/consents/](https://developers.belvo.com/apis/belvoopenapispec/consents/listconsents.md): ## ▢️ 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. ### Get a consent's details - [GET /api/consents/{id}/](https://developers.belvo.com/apis/belvoopenapispec/consents/detailconsent.md): Get the details of a specific consent. ## Owners An **owner** represents the person who has access to a Link and is the owner of all the accounts inside the Link. You can use this endpoint in order to get useful information about your client, such as: - their full name - key contact information - information about the ID document they used when opening the account ### List owners - [GET /api/owners/](https://developers.belvo.com/apis/belvoopenapispec/owners/listowners.md): ## ▢️ Usage With the List Owners method, you can: 1. List owners related to a specific link.id (using the link query parameter). 2. Get the details of a specific owners.id (using the id query parameter). 3. [Not Recommended] List all owners 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. ## 🚨 Deprecated Fields This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field. ### Retrieve owners for a link - [POST /api/owners/](https://developers.belvo.com/apis/belvoopenapispec/owners/retrieveowners.md): Retrieve owner information from a specific link. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Complete an owners request - [PATCH /api/owners/](https://developers.belvo.com/apis/belvoopenapispec/owners/patchowners.md): Used to resume an Owner retrieve session that was paused because an MFA token was required by the institution. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Get an owner's details - [GET /api/owners/{id}/](https://developers.belvo.com/apis/belvoopenapispec/owners/detailowner.md): Get the details of a specific owner. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Delete an owner - [DELETE /api/owners/{id}/](https://developers.belvo.com/apis/belvoopenapispec/owners/destroyowner.md): Delete a specific owner from your Belvo account. ## Accounts An **account** is the representation of a bank account inside a financial institution. A user can have one or more accounts in an institution. For example, one user (or link) can have a checking account, several credit cards, and a loan account. Querying for a user's account information is useful as you can get information regarding: - what types of accounts the user has. - the balance for each account (savings, checking, credit card, loan, and so on). - detailed information regarding their credit card spending. - the current situation of any loans they may have. ### List accounts - [GET /api/accounts/](https://developers.belvo.com/apis/belvoopenapispec/accounts/listaccounts.md): ## ▢️ Usage With the List Accounts method, you can: 1. List accounts related to a specific link.id (using the link query parameter). 2. Get the details of a specific account.id (using the id query parameter). 3. [Not Recommended] List all accounts related to your Belvo account (without using any query parameters). ## πŸ”¦ 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. ## πŸ“– 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. ## 🚨 Deprecated Fields This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field. ### Retrieve accounts for a link - [POST /api/accounts/](https://developers.belvo.com/apis/belvoopenapispec/accounts/retrieveaccounts.md): Retrieve accounts from an existing link. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Complete an accounts request - [PATCH /api/accounts/](https://developers.belvo.com/apis/belvoopenapispec/accounts/patchaccounts.md): Used to resume an Account retrieve session that was paused because an MFA token was required by the institution. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Get an account's details - [GET /api/accounts/{id}/](https://developers.belvo.com/apis/belvoopenapispec/accounts/detailaccount.md): Get the details of a specific account. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Delete an account - [DELETE /api/accounts/{id}/](https://developers.belvo.com/apis/belvoopenapispec/accounts/destroyaccount.md): Delete a specific account from your Belvo account. {% admonition type="danger" name="Rate Limited" %} This endpoint is rate limited. You can only delete 5 items per minute. If you exceed this limit, you will receive a 429 status code. {% /admonition %} {% admonition type="info" %} When you delete an account, all the associated transactions and owner information for that account are also removed. {% /admonition %} ## Balances A balance is the amount of money available in a given bank account (checking or savings) at a given time. ### List balances - [GET /api/br/balances/](https://developers.belvo.com/apis/belvoopenapispec/balances/listbalances.md): ## ▢️ Usage With the List Balances method, you can: 1. [Required] List balances related to a specific link.id (using the link query parameter). 2. [Highly Recommended] List balances related to a specific link.id and account.id (using the link and account query parameters). 2. Get the details of a specific balance.id (using the id query parameter). ## πŸ”¦ 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. ## πŸ“– 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. ## 🚨 Deprecated Fields This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field. ### Retrieve the current balance for a link - [POST /api/br/balances/](https://developers.belvo.com/apis/belvoopenapispec/balances/retrievebalances.md): Retrieve the current account balance for all checking and savings accounts for an existing link. We recommend also sending the account.id so that you receive balances for a specific account. ### Get a balances's details - [GET /api/br/balances/{id}/](https://developers.belvo.com/apis/belvoopenapispec/balances/detailbalance.md): Get the details of a specific balance. ## Exchanges An exchange is a currency exchange operation in the Brazilian Open Finance Network. The resource contains details of foreign exchange operations, including exchange rates, amounts in local and foreign currencies, and settlement information. Each exchange operation can have associated history events that record any modifications to the original contract. ### List exchanges - [GET /api/br/exchanges/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/listexchanges.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} ## ▢️ Usage With the List Exchanges method, you can: 1. [Required] List exchanges related to a specific link.id (using the link query parameter). 2. Get the details of a specific exchange.id (using the id query parameter). ## πŸ”¦ 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. ## πŸ“– 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. ### Retrieve exchanges for a link - [POST /api/br/exchanges/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/retrieveexchanges.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Retrieve exchange operations for an existing link. By default, we retrieve exchange data for the last 365 days. > Note: When you retrieve exchanges, we automatically retrieve the exchange history for each exchange operation found. ### Get an exchange's details - [GET /api/br/exchanges/{id}/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/detailexchange.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Get the details of a specific exchange. > Note: When you delete an exchange, all associated exchange history records are also deleted. ### Delete an exchange - [DELETE /api/br/exchanges/{id}/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/deleteexchange.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Delete a specific exchange from your Belvo account. > Note: When you delete an exchange, all associated exchange history records are also deleted. ### List exchange history for a specific exchange - [GET /api/br/exchanges/{id}/history/](https://developers.belvo.com/apis/belvoopenapispec/exchanges/listexchangehistory.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Get the modification history (audit trail) for a specific exchange operation. ## πŸ“– 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. ## Transactions A **transaction** contains the detailed information of each movement inside an account. For example, a purchase at a store or a restaurant. ### List transactions - [GET /api/transactions/](https://developers.belvo.com/apis/belvoopenapispec/transactions/listtransactions.md): ## ▢️ Usage With the List Transactions method, you can: 1. [Required] List transactions related to a specific link.id (using the link query parameter). 2. Filter the returned transactions using query parameters (see the Filtering responses section below). 3. Get the details of a specific transaction.id (using the id query parameter along with the link 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. ### Retrieve transactions for a link - [POST /api/transactions/](https://developers.belvo.com/apis/belvoopenapispec/transactions/retrievetransactions.md): Retrieve transactions for one or more accounts from a specific link. > πŸ“˜ Transaction Periods and Retrieval > > When retrieving transactions, it is important to understand that the available transaction data ranges depend on each institution. If you try to access older information than what we can access, we will return all the data we can read within that date range. For example, if you request transactions for the last year and we can only access the last six months, we will return the information corresponding to these six months of data. ### Complete a transactions request - [PATCH /api/transactions/](https://developers.belvo.com/apis/belvoopenapispec/transactions/patchtransactions.md): Used to resume a Transaction retrieve session that was paused because an MFA token was required by the institution. ### Get a transaction's details - [GET /api/transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/transactions/detailtransaction.md): Get the details of a specific transaction. ### Delete a transaction - [DELETE /api/transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/transactions/destroytransaction.md): Delete a specific transaction from your Belvo account. > ❗️ Rate limited > > This endpoint is rate limited. You can only delete 5 items per minute. If you exceed this limit, you will receive a 429 status code. ## Bills A **bill** refers to the credit card bill a user receives for a given account. ### List bills - [GET /api/bills/](https://developers.belvo.com/apis/belvoopenapispec/bills/listbills.md): ## ▢️ Usage With the List Bills method, you can: 1. [Required] List bills related to a specific link.id (using the link query parameter). 2. Filter the returned bills using query parameters (see the Filtering responses section below). 3. Get the details of a specific bill.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. ### Retrieve bills for a link - [POST /api/bills/](https://developers.belvo.com/apis/belvoopenapispec/bills/retrievebills.md): Retrieve bills from one or more accounts for a specific link within a specified date range. ### Get a bill's details - [GET /api/bills/{id}/](https://developers.belvo.com/apis/belvoopenapispec/bills/detailbills.md): Get the details of a specific bill. ### Delete a bill - [DELETE /api/bills/{id}/](https://developers.belvo.com/apis/belvoopenapispec/bills/destroybills.md): Delete a specific bill from your Belvo account. ## Investments Brazil ### List investments - [GET /api/br/investments/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/listinvestmentsbrazil.md): ## ▢️ Usage With the List Investments method, you can: 1. [Required] List investments related to a specific link.id (using the link query parameter). 2. Get the details of a specific investment.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. ### Retrieve investments for a link - [POST /api/br/investments/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/retrieveinvestmentsbrazil.md): Retrieve investments for an existing link. ### Get an investment's details - [GET /api/br/investments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/detailinvestmentbrazil.md): Get the details of a specific investment. ### Delete an investment - [DELETE /api/br/investments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investments-brazil/destroyinvestmentbrazil.md): Delete a specific investment from your Belvo account. ## Investment Transactions Brazil ### List investment transactions - [GET /api/br/investment-transactions/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/listinvestmenttransactionsbrazil.md): ## ▢️ Usage With the List Investment Transactions method, you can: 1. [Required] List investment transactions related to a specific link.id (using the link query parameter). 2. Get the details of a specific investment-transaction.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. ### Retrieve investments for a link - [POST /api/br/investment-transactions/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/retrieveinvestmenttransactionsbrazil.md): Retrieve investments for an existing link. ### Get an investment transaction's details - [GET /api/br/investment-transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/detailinvestmenttransactionbrazil.md): Get the details of a specific investment transaction. ### Delete an investment transaction - [DELETE /api/br/investment-transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/investment-transactions-brazil/destroyinvestmenttransactionbrazil.md): Delete a specific investment transaction from your Belvo account. ## Employments Brazil Our employments resource for Brazil lets you get a comprehensive view of your user's current employment history and salary information. For each user, we return the: - work history (including occupations and employer data) - historical and current salary information (per employer) At the moment, the employments resource is available for: - πŸ‡§πŸ‡· Brazil (INSS) ### List employments - [GET /api/br/employments/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/listemploymentsbrazil.md): ## ▢️ Usage With the List Employments method, you can: 1. [Required] List employments related to a specific link.id (using the link query parameter). 2. Get the details of a specific employment.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. ### Retrieve employments for a link - [POST /api/br/employments/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/retrieveemploymentsbrazil.md): Retrieve employments from an existing link. ### Get an employment's details - [GET /api/br/employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/detailemploymentbrazil.md): Get the details of a specific employment. ### Delete an employment - [DELETE /api/br/employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employments-brazil/destroyemploymentbrazil.md): Delete a specific employment from your Belvo account. ## Employment Records Mexico Our employment recordsΒ resource for Mexico lets you get a comprehensive view of your user’s current social security contributions and employment history. With Belvo's employment records resource for Mexico, you can access information about your user's current social security contributions and employment history. For the each user, we return the: - personal data - work history - historical and current daily base salary - and more! At the moment, the employment records resource is available for: - πŸ‡²πŸ‡½Β Mexico (IMSS) - πŸ‡²πŸ‡½Β Mexico (ISSSTE) ### List employment records - [GET /api/employment-records/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/listemploymentrecords.md): ## ▢️ Usage With the List Employment Records method, you can: 1. List employment records related to a specific link.id (using the link query parameter). 2. Get the details of a specific employment-record.id (using the id query parameter). 3. [Not Recommended] List all employment records 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. ### Retrieve employment record details - [POST /api/employment-records/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/retrieveemploymentrecorddetails.md): Retrieve employment record details for an individual. ### Get an employment record's details - [GET /api/employment-records/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/detailemploymentrecord.md): Get the details of a specific employment record. ### Delete an employment record - [DELETE /api/employment-records/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-records-mexico/destroyemploymentrecord.md): Delete a specific employment record from your Belvo account. > ❗️ Rate limited > > This endpoint is rate limited. You can only delete 5 items per minute. If you exceed this limit, you will receive a 429 status code. ## Current Employments Mexico The Current Employments resource provides real-time access to the current employment status of individuals in Mexico. This resource offers detailed information about whether an individual is currently employed or unemployed, along with their active employment records. ## Key Features - **Real-time Employment Status**: Get up-to-date information about an individual's current employment situation - **Current vs Historical**: Unlike Employment Records, this resource focuses specifically on current employment status rather than historical employment data - **Comprehensive Employment Details**: When employed, receive detailed information including employer details, salary information, and employment duration - **Unemployment Status**: Clear indication when an individual is currently unemployed When an individual is **employed**, you will receive: - Personal identification data (name, birth date, NSS, CURP) - Current employment status - Employer information (name, RFC, ID) - Employment location (state) - Duration of employment (days employed) - Salary information (base and monthly salary) ### List current employments - [GET /api/mx/current-employments/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/listcurrentemployments.md): ## ▢️ Usage With the List Current Employments method, you can: 1. List current employments related to a specific link.id (using the link query parameter). 2. Get the details of a specific current-employment.id (using the id query parameter). 3. [Not Recommended] List all current employments 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. ### Retrieve current employments - [POST /api/mx/current-employments/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/retrievecurrentemployments.md): Retrieve current employment information for a specific link.id. ### Get current employment details - [GET /api/mx/current-employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/getcurrentemploymentdetails.md): Get the details of a specific current employment record. ### Delete current employment - [DELETE /api/mx/current-employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/deletecurrentemployment.md): Delete a specific current employment record from your Belvo account. ## Invoices ### List invoices - [GET /api/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices/listinvoices.md): ## ▢️ Usage With the List Invoices method, you can: 1. List invoices related to a specific link.id (using the link query parameter). 2. Get the details of a specific invoice.id (using the id query parameter). 3. [Not Recommended] List all invoices 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. ## 🚨 Deprecated Fields This resource may return deprecated fields. In the response documentation you may see that a field has been marked as deprecated. This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field. ### Retrieve invoices for a link - [POST /api/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices/retrieveinvoices.md): Retrieve invoice information from a specific fiscal link. > πŸ“˜ Info > > You can ask for up to one year (365 days) of invoices per request. If you need invoices for more than one year, just make another request. > 🚧 Warning > > This resource may return deprecated fields. Please check the response documentation for more information. ### Complete an invoices request - [PATCH /api/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices/patchinvoices.md): Used to resume an Invoice retrieve session that was paused because an MFA token was required by the institution. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Get an invoice's details - [GET /api/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices/detailinvoice.md): Get the details of a specific invoice. {% admonition type="info" %} This resource may return deprecated fields. Please check the response documentation for more information. {% /admonition %} ### Delete an invoice - [DELETE /api/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices/destroyinvoice.md): Delete a specific invoice from your Belvo account. ## Tax compliance status ### List tax compliance statuses - [GET /api/tax-compliance-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/listtaxcompliancestatus.md): ## ▢️ Usage With the List Tax Compliance Statuses method, you can: 1. List tax compliance statuses related to a specific link.id (using the link query parameter). 2. Get the details of a specific tax-compliance-status.id (using the id query parameter). 3. [Not Recommended] List all tax compliance statuses 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. ### Retrieve tax compliance statuses for a link - [POST /api/tax-compliance-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/retrievetaxcompliancestatus.md): Retrieve the Tax compliance status information for a specific fiscal link. ### Get a tax compliance status's details - [GET /api/tax-compliance-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/detailtaxcompliancestatus.md): Get the details of a specific Tax compliance status. ### Delete a tax compliance status - [DELETE /api/tax-compliance-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-compliance-status/destroytaxcompliancestatus.md): Delete a specific Tax compliance status from your Belvo account. ## Tax returns ### List tax returns - [GET /api/tax-returns/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/listtaxreturns.md): ## ▢️ Usage With the List Tax Returns method, you can: 1. List tax returns related to a specific link.id (using the link query parameter). 2. Get the details of a specific tax-return.id (using the id query parameter). 3. [Not Recommended] List all tax returns 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. ## πŸ”” Multiple Schemas As a link can have both yearly and monthly tax returns, the response will include a mix of these two types of tax returns (and thus difference schemas). ### Retrieve tax returns for a link - [POST /api/tax-returns/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/retrievetaxreturns.md): Retrieve tax return information for a specific fiscal link. ### Get a tax return's details - [GET /api/tax-returns/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/detailtaxreturn.md): Get the details of a specific tax return. ### Delete a tax return - [DELETE /api/tax-returns/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-returns/destroytaxreturn.md): Delete a specific tax return from your Belvo account. ## Tax retentions ### List tax retentions - [GET /api/tax-retentions/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/listtaxretentions.md): ## ▢️ Usage With the List Tax Retentions method, you can: 1. List tax retentions related to a specific link.id (using the link query parameter). 2. Get the details of a specific tax-retention.id (using the id query parameter). 3. [Not Recommended] List all tax retentions 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. ### Retrieve tax retentions for a link - [POST /api/tax-retentions/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/retrievetaxretentions.md): Retrieve tax retention information from a specific link. The maximum number of tax retentions that can be returned for a period is 500. ### Get a tax retention's details - [GET /api/tax-retentions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/detailtaxretentions.md): Get the details of a specific tax retention. ### Delete a tax retention - [DELETE /api/tax-retentions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-retentions/destroytaxretention.md): Delete a specific tax retention from your Belvo account. ## Tax status ### List tax statuses - [GET /api/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/listtaxstatus.md): ## ▢️ Usage With the List Tax Statuses method, you can: 1. List tax statuses related to a specific link.id (using the link query parameter). 2. Get the details of a specific tax-status.id (using the id query parameter). 3. [Not Recommended] List all tax statuses 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. ### Retrieve tax statuses for a link - [POST /api/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/retrievetaxstatus.md): Retrieve tax status information for a specific fiscal link. ### Get a tax status's details - [GET /api/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/detailtaxstatus.md): Get the details of a specific tax status. ### Delete a tax status - [DELETE /api/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status/destroytaxstatus.md): Delete a specific tax status from your Belvo account. ## Financial Statements ### List Financial Statements - [GET /api/financial-statements/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/listfinancialstatements.md): ## ▢️ Usage With the List Financial Statements method, you can: 1. List financial statements related to a specific link.id (using the link query parameter). 2. Get the details of a specific financial-statement.id (using the id query parameter). 3. [Not Recommended] List all financial statements 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. ### Retrieve Financial Statements for a link - [POST /api/financial-statements/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/retrievefinancialstatements.md): Retrieve the Financial Statements information for a specific fiscal link. ### Get a Financial Statement's details - [GET /api/financial-statements/{id}/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/detailfinancialstatement.md): Get the details of a specific Financial Statement. ### Delete a Financial Statement - [DELETE /api/financial-statements/{id}/](https://developers.belvo.com/apis/belvoopenapispec/financial-statements/destroyfinancialstatement.md): Delete a specific Financial Statement from your Belvo account. ## Invoices Chile ### List invoices - [GET /api/cl/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/listinvoiceschile.md): ## ▢️ Usage With the List Invoices method, you can: 1. List invoices related to a specific link.id (using the link query parameter). 2. Get the details of a specific invoice.id (using the id query parameter). 3. [Not Recommended] List all invoices 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. ### Retrieve invoices for a link - [POST /api/cl/invoices/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/retrieveinvoiceschile.md): Retrieve invoice information from a specific Chilean fiscal link. You can ask for up to one year (365 days) of invoices per request. If you need invoices for more than one year, just make another request. > πŸ“˜ Highly Recommended > > We strongly recommend that you use Belvo's X-Belvo-Request-Mode header parameter and implement an asynchronous workflow. This will ensure that you do not receive any timeout errors while retrieving invoice data. ### Get an invoice's details - [GET /api/cl/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/detailinvoicechile.md): Get the details of a specific invoice. ### Delete an invoice - [DELETE /api/cl/invoices/{id}/](https://developers.belvo.com/apis/belvoopenapispec/invoices-chile/destroyinvoicechile.md): Delete a specific invoice from your Belvo account. ## Tax Status Chile ### List tax statuses - [GET /api/cl/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/listtaxstatuschile.md): ## ▢️ Usage With the Tax Status method, you can: 1. List tax statuses related to a specific link.id (using the link query parameter). 2. Get the details of a specific tax-status.id (using the id query parameter). 3. [Not Recommended] List all tax statuses 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. ### Retrieve tax statuses for a link - [POST /api/cl/tax-status/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/retrievetaxstatuschile.md): Retrieve tax status information for a specific fiscal link. ### Get a tax status's details - [GET /api/cl/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/detailtaxstatuschile.md): Get the details of a specific tax status. ### Delete a tax status - [DELETE /api/cl/tax-status/{id}/](https://developers.belvo.com/apis/belvoopenapispec/tax-status-chile/destroytaxstatuschile.md): Delete a specific tax status from your Belvo account. ## Debt Reports Chile ### List debts reports - [GET /api/cl/debt-reports/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/listdebtreportchile.md): ## ▢️ Usage With the List Debt Reports method, you can: 1. List debt reports related to a specific link.id (using the link query parameter). 2. Get the details of a specific debt-report.id (using the id query parameter). 3. [Not Recommended] List all debt reports 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. ### Retrieve debt details for a link - [POST /api/cl/debt-reports/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/retrievedebtreportchile.md): Retrieve debt reports information for a specific fiscal link. ### Get a debt's details - [GET /api/cl/debt-reports/{id}/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/detaildebtreportchile.md): Get the details of a specific debt. ### Delete a debt report - [DELETE /api/cl/debt-reports/{id}/](https://developers.belvo.com/apis/belvoopenapispec/debt-reports-chile/destroydebtreportchile.md): Delete a specific debt report from your Belvo account. ## Incomes Use the Incomes endpoint to gather insights on an account's income sources for the past 365 days. The endpoint is particularly useful when you want to verify a person's income. > πŸ“˜ Info > > The incomes resource is **only** available for Checking and Savings accounts associated with banking links. ### List incomes - [GET /api/incomes/](https://developers.belvo.com/apis/belvoopenapispec/incomes/listincomes.md): ## ▢️ Usage With the List Incomes method, you can: 1. List incomes related to a specific link.id (using the link query parameter). 2. Get the details of a specific income.id (using the id query parameter). 3. [Not Recommended] List all incomes 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. ### Retrieve incomes for a link - [POST /api/incomes/](https://developers.belvo.com/apis/belvoopenapispec/incomes/retrieveincome.md): Retrieve income insights for checking and savings accounts from a specific link. You can receive insights for a period of up to 365 days, depending on the transaction history available for each institution. ### Complete an incomes request - [PATCH /api/incomes/](https://developers.belvo.com/apis/belvoopenapispec/incomes/patchincomes.md): Used to resume an Income retrieve session that was paused because an MFA token was required by the institution. ### Get an income's details - [GET /api/incomes/{id}/](https://developers.belvo.com/apis/belvoopenapispec/incomes/detailincome.md): Get the details of a specific income. ### Delete an income - [DELETE /api/incomes/{id}/](https://developers.belvo.com/apis/belvoopenapispec/incomes/destroyincomes.md): Delete a specific income from your Belvo account. ## Recurring Expenses Belvo's Recurring Expenses API allows you to identify a user's regular payments for subscription services, such as Netflix or gym memberships, as well as utility payments, such as electricity or phone bills. We return information for up to 365 days. > πŸ“˜ Info > > The recurring expenses resource is **only** available for Checking, Savings and Credit Card accounts associated with banking links. ### List recurring expenses - [GET /api/recurring-expenses/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/listrecurringexpenses.md): ## ▢️ Usage With the List Recurring Expenses method, you can: 1. List recurring expenses related to a specific link.id (using the link query parameter). 2. Get the details of a specific recurring-expense.id (using the id query parameter). 3. [Not Recommended] List all recurring expenses 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. ### Retrieve recurring expenses for a link - [POST /api/recurring-expenses/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/retrieverecurringexpenses.md): Retrieve recurring expense insights for checking and savings accounts from a specific link. You can receive insights for a period of up to 365 days, depending on the transaction history available for each institution. ### Complete a recurring expenses request - [PATCH /api/recurring-expenses/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/patchrecurringexpenses.md): Used to resume an Recurring Expenses retrieve session that was paused because an MFA token was required by the institution. ### Get a recurring expense's details - [GET /api/recurring-expenses/{id}/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/detailrecurringexpense.md): Get the details of a specific recurring expense. ### Delete a recurring expense - [DELETE /api/recurring-expenses/{id}/](https://developers.belvo.com/apis/belvoopenapispec/recurring-expenses/destroyrecurringexpense.md): Delete a specific recurring expense from your Belvo account. ## Risk Insights ### List risk insights - [GET /api/risk-insights/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/listriskinsights.md): ## ▢️ Usage With the List Risk Insights method, you can: 1. List risk insights related to a specific link.id (using the link query parameter). 2. Get the details of a specific risk-insight.id (using the id query parameter). 3. [Not Recommended] List all risk insights 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. ### Retrieve risk insights for a link - [POST /api/risk-insights/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/retrieveriskinsights.md): Request the risk insights for a given link ID. If you need to know the currency of the account, just do a GET Details to the accounts endpoint (using the ID you receive from the accounts response). ### Complete a risk insights request - [PATCH /api/risk-insights/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/patchriskinsights.md): Used to resume an Risk insights retrieve session that was paused because an MFA token was required by the institution. ### Get a risk insight's details - [GET /api/risk-insights/{id}/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/detailriskinsights.md): Get the details of a specific risk insight. ### Delete a risk insight - [DELETE /api/risk-insights/{id}/](https://developers.belvo.com/apis/belvoopenapispec/risk-insights/destroyriskinsights.md): Delete a specific risk insight from your Belvo account. ## Employment Metrics ### List employment metrics - [GET /api/employment-metrics/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/listemploymentmetrics.md): ## ▢️ Usage With the List Employment Metrics method, you can: 1. List employment metrics related to a specific link.id (using the link query parameter). 2. Get the details of a specific employment-metric.id (using the id query parameter). 3. [Not Recommended] List all employment metrics 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. ### Retrieve employment metrics - [POST /api/employment-metrics/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/retrieveemploymentmetricdetails.md): Retrieve employment metrics for an individual. > Note: Before requesting employment metrics, make sure to first make a POST Retrieve employment record details request. ### Get an employment metric's details - [GET /api/employment-metrics/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/detailemploymentmetric.md): Get the details of a specific employment metric. ### Delete an employment metric - [DELETE /api/employment-metrics/{id}/](https://developers.belvo.com/apis/belvoopenapispec/employment-metrics/destroyemploymentmetric.md): Delete a specific employment metric from your Belvo account. ## Payment Institutions (Brazil) A **payment institution** is an entity that Belvo can access information from. You can see a complete list of institutions available for payments by making a List request to this endpoint. ### List all payment institutions - [GET /payments/br/institutions/](https://developers.belvo.com/apis/belvoopenapispec/payment-institutions-(brazil)/listpaymentinstitutionsbrazil.md): List all available payment institutions. ## Customers (Brazil) A **customer** is the payer that's going to push funds into your bank account. You need to create a customer in order to receive inflow payments to your organization's bank account. {% admonition type="info" name="Resource Versioning" %} This endpoint supports resource-level versioning. By including the header `X-Belvo-API-Resource-Version: Payments-BR.V2`, you can access the latest (V2) request and response formats. If the header is not provided, the default (V1) format will be used. See the API documentation for details on the differences between versions. {% /admonition %} ### Create a new customer - [POST /payments/br/customers/](https://developers.belvo.com/apis/belvoopenapispec/customers-(brazil)/createcustomerbrazil.md): Create a new customer to send or request funds. ### List all customers - [GET /payments/br/customers/](https://developers.belvo.com/apis/belvoopenapispec/customers-(brazil)/listcustomersbrazil.md): List all customers associated with your Belvo account. ### Get details about a customer - [GET /payments/br/customers/{id}/](https://developers.belvo.com/apis/belvoopenapispec/customers-(brazil)/detailcustomerbrazil.md): Get the details about a specific customer ## Bank Accounts (Brazil) To receive inflow payments to your organization's bank account, you must register the bank accounts (individual and business) using Belvo's Payments API. - **Individual** bank accounts must be created for each payer (your customer). - **Business** bank accounts need to be created for the beneficiary of the payment (your organization). {% admonition type="info" name="Resource Versioning" %} This endpoint supports resource-level versioning. By including the header `X-Belvo-API-Resource-Version: Payments-BR.V2`, you can access the latest (V2) request and response formats. If the header is not provided, the default (V1) format will be used. See the API documentation for details on the differences between versions. {% /admonition %} ### Register a new bank account - [POST /payments/br/bank-accounts/](https://developers.belvo.com/apis/belvoopenapispec/bank-accounts-(brazil)/registerbankaccountbrazil.md): Register a new bank account from which to send or request funds. ### List all bank accounts - [GET /payments/br/bank-accounts/](https://developers.belvo.com/apis/belvoopenapispec/bank-accounts-(brazil)/listbankaccountbrazil.md): List all bank accounts associated with your Belvo account. ### Get details about a bank account - [GET /payments/br/bank-accounts/{id}/](https://developers.belvo.com/apis/belvoopenapispec/bank-accounts-(brazil)/detailbankaccountbrazil.md): Get the details about a specific bank account ## Payment Authorizations (Brazil) A Payment Authorization is the consent that your user gives you to charge (debit money from) their accounts. You need to perform one Payment Authorization per β€˜contract’ (for example, if your company does both electricity and water but they are billed separately, then you will create two separate Payment Authorizations). Once the user confirms the authorization, you will need to listen for a a `PAYMENT_AUTHORIZATION` webhook with the status set to `AUTHORIZED`. Once you receive this webhook, the authorization process is complete, and you will be able to charge your user. {% admonition type="info" name="What is a charge?" %} A **charge** represents the individual payment (debit) that your customer will make. {% /admonition %} {% admonition type="danger" name="Version Header" %} The Payment Authorization resource requires that you send through the `X-Belvo-API-Resource-Version` header set to `Payments-BR.V2`. {% /admonition %} ### Create a new Payment Authorization - [POST /payments/br/payment-authorizations/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/createpaymentauthorizationbrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Create a Payment Authorization. ### List all Payment Authorizations - [GET /payments/br/payment-authorizations/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationsbrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} List all Payment Authorizations associated with your Belvo account. ### Get details about a Payment Authorization - [GET /payments/br/payment-authorizations/{payment_authorization_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationbrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Get the details about a specific Payment Authorization. ### Cancel a Payment Authorization - [POST /payments/br/payment-authorizations/{payment_authorization_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationbrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Cancel a Payment Authorization We respond with a 204 - No Content and will inform you via webhook that the Payment Authorization was canceled successfully. {% admonition type="warning" name="Cancellation Time Restrictions" %} The latest you can cancel a Payment Authorization is by 22:00:00 (GMT-3) on the day before the next Charge date. If you miss the cutoff time, the Payment Authorization will be cancelled, but the Charge will still be processed. {% /admonition %} ### List all Charges for a Payment Authorization - [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/listpaymentauthorizationchargesbrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} List all Charges associated with a Payment Authorization ### Get details about a Charge for a Payment Authorization - [GET /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/detailpaymentauthorizationchargebrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Get the details about a specific Charge associated with a Payment Authorization. ### Retry a failed Charge for a Payment Authorization - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/retry/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/retrypaymentauthorizationchargebrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Retry a failed Charge for a given Payment Authorization. {% admonition type="warning" name="Additional documentation" %} Please make sure to read the dedicated Retrying Charges and Linked Charges documentation before attempting to retry a charge. {% /admonition %} ### Cancel a scheduled Charge - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/cancelpaymentauthorizationchargebrazil.md): {% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development.. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Cancel a scheduled Charge. We respond with a 204 - No Content and will inform you via webhook that the charge was canceled successfully. {% admonition type="warning" name="Cancellation Time Restriction" %} The latest you can cancel a scheduled Charge is by 22:00:00 (GMT-3) on the day before the Charge date. If you miss the cutoff time, you will receive an API error from Belvo and the payment will go through. {% /admonition %} ## Charges (Brazil) ### Get details about a Charge - [GET /payments/br/charges/{charge_id}/](https://developers.belvo.com/apis/belvoopenapispec/charges-(brazil)/detailchargebrazil.md): Get the details about a specific Charge. ## Payment Intents (Brazil) A **payment intent** is a single point of access to create payments using any payment method offered by Belvo. A payment intent captures all payment information (such as the amount to be charged, the description of the payment, the provider, and so on) and guides your customers through the payment flow. ### Create a new Payment Intent - [POST /payments/br/payment-intents/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/createpaymentintentbrazil.md): Create a Payment Intent. You can create Payment Intent in the following configurations: |Beneficiary|Customer (Payer)|Example| |---|---|---| |Pix Key|Already registered with Belvo|Pix Key (With Existing Customer)| |Pix Key|Register with Belvo at time of Payment Intent request|Pix Key (With New Customer)| |Bank Account (Already Registered)|Already Registered |Bank Account (With Existing Customer)| |Bank Account (Already Registered)|Register with Belvo at time of Payment Intent request|Bank Account (With New Customer)| |Bank Account (Register at time of Payment Intent request)|Register with Belvo at time of Payment Intent request|Bank Account (With New Customer and Beneficiary Bank Account)| {% admonition type="warning" name="Pix Payments" %} When you create Payment Intents using a Pix Key, you have to make a PATCH Complete a Payment Intent request to complete the Payment Intent creation. {% /admonition %} ### List all payment intents - [GET /payments/br/payment-intents/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/listpaymentintentsbrazil.md): List all payment intents associated with your Belvo account. ### Complete a payment intent - [PATCH /payments/br/payment-intents/{id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/patchpaymentintentbrazil.md): Complete a new payment intent. ### Get details about a payment intent - [GET /payments/br/payment-intents/{id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/detailpaymentintentbrazil.md): Get the details about a specific payment intent. ### Cancel a scheduled payment intent - [POST /payments/br/payment-intents/{id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/cancelpaymentintentbrazil.md): Cancel a scheduled (one-off) payment intent. We respond with a 204 - No Content and will inform you via webhook that the payment intent was canceled successfully. > Note: The latest you can cancel a scheduled payment intent is by 23:59:00 (GMT-3) on the day before the scheduled payment date. ### List all charges for a payment intent - [GET /payments/br/payment-intents/{payment_intent_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/listchargesbrazil.md): List all charges associated with a payment intent. ### Get details about a charge for a payment intent - [GET /payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/detailchargesbrazil.md): Get the details about a specific charge associated with a payment intent. ### Cancel a scheduled charge - [POST /payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/](https://developers.belvo.com/apis/belvoopenapispec/payment-intents-(brazil)/cancelchargebrazil.md): Cancel a scheduled charge. We respond with a 204 - No Content and will inform you via webhook that the charge was canceled successfully. > Note: The latest you can cancel a scheduled charge is by 23:59:00 (GMT-3) on the day before the scheduled payment date. ## Biometric Pix Widget Access Token (Brazil) Use the Biometric Pix Widget Token requests to create a access token for Biometric Payments. ### Generate a payment widget access token - [POST /payments/br/token/](https://developers.belvo.com/apis/belvoopenapispec/biometric-pix-widget-access-token-(brazil)/generatepaymentwidgetaccesstoken.md): Generate a payment widget access token for the Biometric Pix enrollment or payment process. ## Enrollments (Brazil) ### Enroll a new user device - [POST /payments/br/enrollments/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/createenrollmentbrazil.md): ## ▢️ Usage With the Enroll a new user device method, you can begin the enrollment process for a new device to allow for Biometric Pix payments. > 🚧 Create a customer first > > Before you can enroll a user device, you must first create a customer. ### List enrollments - [GET /payments/br/enrollments/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/listenrollmentsbrazil.md): ## ▢️ Usage With the List Enrollments method, you can: 1. (Recommended) List enrollments related to a specific CPF (using the customer__identifier query parameter). 2. List enrollments related to a specific customer.id and institution.id (using the customer and institution query parameters). 3. List enrollments according to a specific status (using the status query parameter). 4. [Not Recommended] List all enrollements related to your Belvo account (without using any query parameters). ## πŸ”¦ 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. ## πŸ“– 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. ### Get details about an enrollment - [GET /payments/br/enrollments/{enrollment_id}/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/detailenrollmentbrazil.md): Get details regarding a specific device enrollment. ### Complete enrollment after redirection - [POST /payments/br/enrollments/complete-redirection/](https://developers.belvo.com/apis/belvoopenapispec/enrollments-(brazil)/completeenrollmentredirectionbrazil.md): ## ▢️ Usage Use this endpoint to complete the enrollment process after the user is redirected back from the institution. The request body should match the parameters received in the callback URL, either for a successful or error callback. ## Payment Transactions (Brazil) Each time you receive an inflow payment from your customer, a **transaction** is created in the Belvo database. You can use the Payment Transactions resource in order to get useful information about a transaction as well as the specific charge associated with it. ### List all payment transactions - [GET /payments/br/transactions/](https://developers.belvo.com/apis/belvoopenapispec/payment-transactions-(brazil)/listpaymenttransactionsbrazil.md): List all payment transactions associated with your Belvo account. ### Get details about a payment transaction - [GET /payments/br/transactions/{id}/](https://developers.belvo.com/apis/belvoopenapispec/payment-transactions-(brazil)/detailpaymenttransactionsbrazil.md): Get the details about a specific payment transaction.