# Retrieve exchanges for a link

{% 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.

Endpoint: POST /api/br/exchanges/
Version: 1.223.0
Security: basicAuth

## Query parameters:

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

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

## Request fields (application/json):

  - `link` (string, required)
    The link.id you want to retrieve information for.
    Example: "c81a1dea-6dd6-4999-8b9f-541ee8197058"

  - `date_from` (string)
    The starting date for which you want to retrieve exchange data, in YYYY-MM-DD format. If not provided, we retrieve data for the last 365 days.
    Example: "2022-01-01"

  - `date_to` (string)
    The ending date for which you want to retrieve exchange data, in YYYY-MM-DD format. If not provided, we retrieve data up to today.
    Example: "2022-12-31"

  - `save_data` (boolean)
    Indicates whether or not to persist the data in Belvo. By default, this is set to true and we return a 201 Created response.

When set to false, the data won't be persisted and we return a 200 OK response.
    Example: true

## Response 200 fields (application/json):

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

  - `link` (string,null, required)
    The link.id the data belongs to.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

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

  - `collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2022-02-09T08:45:50.406032Z"

  - `operation_identifier` (string, required)
    The network's unique identifier for the exchange operation.
    Example: "92792126019929240"

  - `operation_number` (string,null)
    The 12-digit operation registration number from the Brazil Central Bank (Bacen). This can be null if the operation has not yet been registered.
    Example: "393874649456"

  - `operation_type` (string, required)
    The type of exchange operation.

We return one of the following enum values:
  - COMPRA - Buy (client is buying foreign currency)
  - VENDA - Sell (client is selling foreign currency)
    Enum: "COMPRA", "VENDA"

  - `operation_requested_at` (string, required)
    The ISO-8601 timestamp when the exchange operation was contracted.
    Example: "2023-03-07T08:30:00Z"

  - `authorized_institution_identifier` (integer, required)
    The CNPJ of the institution authorized to conduct the operation.
    Example: 11225860000140

  - `authorized_institution_name` (string, required)
    The name of the authorized institution.
    Example: "AGENCIA CORRETORA"

  - `intermediary_institution_identifier` (integer,null)
    The CNPJ of the intermediary institution, if one was used.
    Example: 11225860000140

  - `intermediary_institution_name` (string,null)
    The name of the intermediary institution. Must be present if intermediary_institution_identifier is available.
    Example: "AGENCIA CORRETORA"

  - `operation_due_date` (string, required)
    The currently scheduled settlement date for the operation, in YYYY-MM-DD format. 

> Note: This field is updated if any changes are made to the exchange operation.
    Example: "2018-02-15"

  - `local_operation_tax_amount` (number, required)
    The exchange rate applied to the operation.
    Example: 1.3

  - `local_operation_tax_currency` (string, required)
    The three-letter currency code (ISO-4217) for the exchange rate.
    Example: "BRL"

  - `local_operation_value_amount` (number, required)
    The total value of the operation in local currency.
    Example: 1000.04

  - `local_operation_value_currency` (string, required)
    The three-letter currency code (ISO-4217) for the local currency.
    Example: "BRL"

  - `foreign_operation_value_amount` (number, required)
    The total value of the operation in the foreign currency.
    Example: 1000.04

  - `foreign_operation_value_currency` (string, required)
    The three-letter currency code (ISO-4217) for the foreign currency.
    Example: "USD"

  - `operation_outstanding_balance_amount` (number,null)
    The outstanding balance to be settled, in the foreign currency. In the case that the exchange operation is scheduled to be settled within two days of the operation_requested_at, this value can be null.
    Example: 1000.04

  - `operation_outstanding_balance_currency` (string,null)
    The currency of the outstanding balance. Required if operation_outstanding_balance_amount is not null.
    Example: "USD"

  - `tev_amount_amount` (number,null)
    The "All-in Rate" (Valor Efetivo Total/Total Effective Cost), representing the total cost of the operation. Required when the operation is scheduled to be settled within two days of the operation_requested_at and does not exceed $100,000 USD.
    Example: 1000.000004

  - `tev_amount_currency` (string,null)
    The currency of the VET (always BRL). Required if tev_amount_amount is not null.
    Example: "BRL"

  - `local_currency_advance_percentage` (number,null)
    The percentage of the foreign currency value that was granted to the client in advance. In the case that the exchange operation is scheduled to be settled within two days of the operation_requested_at, this value can be null.
    Example: 0.12

  - `settlement_method` (string,null, required)
    The method of delivery for the foreign currency.

We return one of the following enum values:
  - CARTA_CREDITO_A_VISTA (Code 10) - Sight letter of credit
  - CARTA_CREDITO_A_PRAZO (Code 15) - Term letter of credit
  - CONTA_DEPOSITO (Code 20) - Deposit account
  - CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS (Code 21) - Foreign currency deposit account in country
  - CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR (Code 22) - Exporter's deposit account maintained abroad
  - CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR (Code 23) - Deposit account or payment to exporter at foreign institution
  - CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS (Code 25) - Reciprocal payments and credits agreement
  - CHEQUE (Code 30) - Check
  - ESPECIE_CHEQUES_VIAGEM (Code 50) - Cash or traveler's checks
  - CARTAO_PREPAGO (Code 55) - Prepaid card
  - TELETRANSMISSAO (Code 65) - Wire transfer
  - TITULOS_VALORES (Code 75) - Securities/bonds
  - SIMBOLICA (Code 90) - Symbolic
  - SEM_MOVIMENTACAO_VALORES (Code 91) - No movement of funds
  - DEMAIS (Code 99) - Others
  - OUTRO_NAO_MAPEADO_OFB - Other not mapped by Open Finance Brazil
  - null
    Enum: "CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS", "CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR", "ESPECIE_CHEQUES_VIAGEM", "CARTAO_PREPAGO", "TELETRANSMISSAO", "SEM_MOVIMENTACAO_VALORES", "DEMAIS", "CARTA_CREDITO_A_VISTA", "CARTA_CREDITO_A_PRAZO", "CONTA_DEPOSITO", "CHEQUE", "TITULOS_VALORES", "SIMBOLICA", "CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR", "CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS", "OUTRO_NAO_MAPEADO_OFB", null

  - `operation_category_code` (string, required)
    The 5-digit Central Bank code that classifies the "nature" of the operation.

This code must comply with the nature codes referenced in Resolution 277 or Circular 3690, as applicable to the exchange contract.
    Example: "90302"

## Response 201 fields (application/json):

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

  - `link` (string,null, required)
    The link.id the data belongs to.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

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

  - `collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2022-02-09T08:45:50.406032Z"

  - `operation_identifier` (string, required)
    The network's unique identifier for the exchange operation.
    Example: "92792126019929240"

  - `operation_number` (string,null)
    The 12-digit operation registration number from the Brazil Central Bank (Bacen). This can be null if the operation has not yet been registered.
    Example: "393874649456"

  - `operation_type` (string, required)
    The type of exchange operation.

We return one of the following enum values:
  - COMPRA - Buy (client is buying foreign currency)
  - VENDA - Sell (client is selling foreign currency)
    Enum: "COMPRA", "VENDA"

  - `operation_requested_at` (string, required)
    The ISO-8601 timestamp when the exchange operation was contracted.
    Example: "2023-03-07T08:30:00Z"

  - `authorized_institution_identifier` (integer, required)
    The CNPJ of the institution authorized to conduct the operation.
    Example: 11225860000140

  - `authorized_institution_name` (string, required)
    The name of the authorized institution.
    Example: "AGENCIA CORRETORA"

  - `intermediary_institution_identifier` (integer,null)
    The CNPJ of the intermediary institution, if one was used.
    Example: 11225860000140

  - `intermediary_institution_name` (string,null)
    The name of the intermediary institution. Must be present if intermediary_institution_identifier is available.
    Example: "AGENCIA CORRETORA"

  - `operation_due_date` (string, required)
    The currently scheduled settlement date for the operation, in YYYY-MM-DD format. 

> Note: This field is updated if any changes are made to the exchange operation.
    Example: "2018-02-15"

  - `local_operation_tax_amount` (number, required)
    The exchange rate applied to the operation.
    Example: 1.3

  - `local_operation_tax_currency` (string, required)
    The three-letter currency code (ISO-4217) for the exchange rate.
    Example: "BRL"

  - `local_operation_value_amount` (number, required)
    The total value of the operation in local currency.
    Example: 1000.04

  - `local_operation_value_currency` (string, required)
    The three-letter currency code (ISO-4217) for the local currency.
    Example: "BRL"

  - `foreign_operation_value_amount` (number, required)
    The total value of the operation in the foreign currency.
    Example: 1000.04

  - `foreign_operation_value_currency` (string, required)
    The three-letter currency code (ISO-4217) for the foreign currency.
    Example: "USD"

  - `operation_outstanding_balance_amount` (number,null)
    The outstanding balance to be settled, in the foreign currency. In the case that the exchange operation is scheduled to be settled within two days of the operation_requested_at, this value can be null.
    Example: 1000.04

  - `operation_outstanding_balance_currency` (string,null)
    The currency of the outstanding balance. Required if operation_outstanding_balance_amount is not null.
    Example: "USD"

  - `tev_amount_amount` (number,null)
    The "All-in Rate" (Valor Efetivo Total/Total Effective Cost), representing the total cost of the operation. Required when the operation is scheduled to be settled within two days of the operation_requested_at and does not exceed $100,000 USD.
    Example: 1000.000004

  - `tev_amount_currency` (string,null)
    The currency of the VET (always BRL). Required if tev_amount_amount is not null.
    Example: "BRL"

  - `local_currency_advance_percentage` (number,null)
    The percentage of the foreign currency value that was granted to the client in advance. In the case that the exchange operation is scheduled to be settled within two days of the operation_requested_at, this value can be null.
    Example: 0.12

  - `settlement_method` (string,null, required)
    The method of delivery for the foreign currency.

We return one of the following enum values:
  - CARTA_CREDITO_A_VISTA (Code 10) - Sight letter of credit
  - CARTA_CREDITO_A_PRAZO (Code 15) - Term letter of credit
  - CONTA_DEPOSITO (Code 20) - Deposit account
  - CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS (Code 21) - Foreign currency deposit account in country
  - CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR (Code 22) - Exporter's deposit account maintained abroad
  - CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR (Code 23) - Deposit account or payment to exporter at foreign institution
  - CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS (Code 25) - Reciprocal payments and credits agreement
  - CHEQUE (Code 30) - Check
  - ESPECIE_CHEQUES_VIAGEM (Code 50) - Cash or traveler's checks
  - CARTAO_PREPAGO (Code 55) - Prepaid card
  - TELETRANSMISSAO (Code 65) - Wire transfer
  - TITULOS_VALORES (Code 75) - Securities/bonds
  - SIMBOLICA (Code 90) - Symbolic
  - SEM_MOVIMENTACAO_VALORES (Code 91) - No movement of funds
  - DEMAIS (Code 99) - Others
  - OUTRO_NAO_MAPEADO_OFB - Other not mapped by Open Finance Brazil
  - null
    Enum: "CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS", "CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR", "ESPECIE_CHEQUES_VIAGEM", "CARTAO_PREPAGO", "TELETRANSMISSAO", "SEM_MOVIMENTACAO_VALORES", "DEMAIS", "CARTA_CREDITO_A_VISTA", "CARTA_CREDITO_A_PRAZO", "CONTA_DEPOSITO", "CHEQUE", "TITULOS_VALORES", "SIMBOLICA", "CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR", "CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS", "OUTRO_NAO_MAPEADO_OFB", null

  - `operation_category_code` (string, required)
    The 5-digit Central Bank code that classifies the "nature" of the operation.

This code must comply with the nature codes referenced in Resolution 277 or Circular 3690, as applicable to the exchange contract.
    Example: "90302"

## Response 403 fields (application/json):

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


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

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


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

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

## Response 408 fields (application/json):

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


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

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


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

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

## Response 428 fields (application/json):

  - `code` (string)
    A unique error code (token_required) that allows you to classify and handle the error programmatically.
ℹ️ Check our DevPortal for more information on how to handle 428 token_required errors.
    Example: "token_required"

  - `message` (string)
    A short description of the error. 
For token_required errors, the description is:
  
  - A MFA token is required by the institution to login.
    Example: "A MFA token is required by the institution to login"

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

  - `session` (string)
    A 32-character unique ID of the login session (matching a regex pattern of: [a-f0-9]{32}).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Session duration time in seconds.
    Example: 9600

  - `link` (string)
    Unique identifier created by Belvo, used to reference the current
Link.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Details on how to generate the token.

  - `token_generation_data.instructions` (string)
    Instructions for token generation.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Type of the data to generate the token (QR code, numeric
challenge).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Value to use to generate the token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indicates whether the user needs to provide input in order to complete the authentication.
When set to false, your user may need to:
- confirm the login on another device
- scan a QR code
You will still need to make a PATCH call to complete the request.
    Example: true

## Response 500 fields (application/json):

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


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

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


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

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