# 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.222.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/_spec/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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). ## ๐Ÿ“– Pagination This method returns a paginated response (default: 100 items per page). You can use the query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 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 to or from to . - Modify they period for the link. - Modify the historical resources you want to retrieve for the link (). ## Changing a link's When you change a link from to , the next day a historical update of the core resources for the link is triggered (resulting in you receiving webhooks for the link). You are billed for these historical updates. ## Modifying If you only modify the 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 . ## Modifying If you only modify the for a link, this will not trigger a historical update. In order to trigger a historical update for the link, you must change the . ### 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 header to 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 status and provide a request ID for tracking the deletion process. Once the process is complete, you will receive a webhook notification. If you do not set this header, the endpoint will respond with a status, but you will be subject to the rate limit of 5 deletions per minute. If you exceed this limit, you will receive a 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 error with the message . {% /admonition %} Use this method to trigger a historical update for a specific link (single or recurrent). Use the 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 status code and a that you can later use to associate a given 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 permanently, you should use the 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 the OFDA or Banking Aggregation 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 . 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 . 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 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. List balances related to a specific (using the query parameter). 2. List balances related to a specific and (using the and query parameters). 2. Get the details of a specific (using the 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 . 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 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. ## 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. List transactions related to a specific (using the query parameter). 2. Filter the returned transactions using query parameters (see the Filtering responses section below). 3. Get the details of a specific (using the query parameter along with the query parameter). ## ๐Ÿ“– Pagination This method returns a paginated response (default: 100 items per page). You can use the query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 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. List bills related to a specific link.id (using the 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 query parameter). ## ๐Ÿ“– Pagination This method returns a paginated response (default: 100 items per page). You can use the query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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. List investments related to a specific (using the query parameter). 2. Get the details of a specific (using the query parameter). ## ๐Ÿ“– Pagination This method returns a paginated response (default: 100 items per page). You can use the query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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. List investment transactions related to a specific (using the query parameter). 2. Get the details of a specific (using the query parameter). ## ๐Ÿ“– Pagination This method returns a paginated response (default: 100 items per page). You can use the query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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. List employments related to a specific (using the query parameter). 2. Get the details of a specific (using the query parameter). ## ๐Ÿ“– Pagination This method returns a paginated response (default: 100 items per page). You can use the query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 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): {% admonition type="success" name="Coming Soon!" %} This resource is currently in development and as such certain field names or values may change. {% /admonition %} ## โ–ถ๏ธ Usage With the List Current Employments method, you can: 1. List current employments related to a specific (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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): {% admonition type="success" name="Coming Soon!" %} This resource is currently in development and as such certain field names or values may change. {% /admonition %} Retrieve current employment information for a specific . ### Get current employment details - [GET /api/mx/current-employments/{id}/](https://developers.belvo.com/apis/belvoopenapispec/current-employments-mexico/getcurrentemploymentdetails.md): {% admonition type="success" name="Coming Soon!" %} This resource is currently in development and as such certain field names or values may change. {% /admonition %} 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): {% admonition type="success" name="Coming Soon!" %} This resource is currently in development and as such certain field names or values may change. {% /admonition %} 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 . 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 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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 (using the query parameter). 2. Get the details of a specific (using the query parameter). 3. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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. > 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="In BETA" %} This endpoint is in BETA. 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="In BETA" %} This endpoint is in BETA. 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="In BETA" %} This endpoint is in BETA. 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="In BETA" %} This endpoint is in BETA. 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 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, . {% /admonition %} ### Create a new Charge - [POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/](https://developers.belvo.com/apis/belvoopenapispec/payment-authorizations-(brazil)/createpaymentauthorizationchargebrazil.md): {% admonition type="warning" name="In BETA" %} This endpoint is in BETA. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} Create a new Charge for a Payment Authorization. ### 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="In BETA" %} This endpoint is in BETA. 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="In BETA" %} This endpoint is in BETA. 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="In BETA" %} This endpoint is in BETA. 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="In BETA" %} This endpoint is in BETA. 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 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): {% admonition type="warning" name="In BETA" %} This endpoint is in BETA and applicable for . 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. ## 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. > **Note:** For institutions that require the `username_type` in the `form_fields` array, you must send through this value in your PATCH request. ### 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 use this method to additionally create a customer and a payment intent in a single request (see the Customer and Payment Intent option). ### 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 and will inform you via webhook that the payment intent was canceled successfully. > : The latest you can cancel a scheduled payment intent is by on the day 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 and will inform you via webhook that the charge was canceled successfully. > : The latest you can cancel a scheduled charge is by on the day 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 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 query parameter). 2. List enrollments related to a specific and (using the and query parameters). 3. List enrollments according to a specific status (using the query parameter). 4. 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 query parameter to increase the number of items returned to a maximum of 1000 items. You can use the 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.