# List exchange history for a specific exchange

{% admonition type="warning" name="Coming Soon" %}
  This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative.
{% /admonition %}

Get the modification history (audit trail) for a specific exchange operation.

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

Endpoint: GET /api/br/exchanges/{id}/history/
Version: 1.223.0
Security: basicAuth

## Path parameters:

  - `id` (string, required)
    The exchange.id you want to get the history for.

## Query parameters:

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

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

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

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    An array of exchange history objects.

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

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

  - `results.exchange_id` (string, required)
    The Belvo-generated unique identifier for the original exchange operation.
    Example: "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321"

  - `results.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"

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

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

  - `results.event_sequence_number` (string, required)
    The sequence number of the event record at the Central Bank (Bacen).
    Example: "493874649457"

  - `results.event_type` (integer, required)
    The type of event that occurred for the exchange operation.

We return one of the following enum values:
  - 1 - Contract in the primary market
  - 2 - Modification of exchange operation in the primary market
  - 3 - Cancellation of exchange operation in the primary market
  - 4 - Settlement of exchange operation in the primary market
  - 5 - Write-off of outstanding amount to be settled in the primary market
  - 6 - Reinstatement of written-off outstanding amount in the primary market
  - 9 - Nullification of exchange operation in the primary market (used, for example, in the nullification of a settlement/cancellation event)

> Note: Codes follow the messaging layout sent by institutions to the Central Bank of Brazil.
    Enum: 1, 2, 3, 4, 5, 6, 9

  - `results.event_created_at` (string, required)
    The ISO-8601 timestamp when the event occurred.
    Example: "2023-03-10T14:00:00Z"

  - `results.operation_due_date` (string,null)
    The date when the operation (buy or sell), after the event, is scheduled to be settled, in YYYY-MM-DD format.
    Example: "2023-03-20"

  - `results.local_operation_tax_amount` (number,null)
    The exchange rate applied to the operation after the event.
    Example: 1.4

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

  - `results.local_operation_value_amount` (number,null)
    The total value of the operation in local currency after the event.
    Example: 950

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

  - `results.foreign_operation_value_amount` (number,null)
    The total value of the operation in foreign currency after the event.
    Example: 678.57

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

  - `results.operation_outstanding_balance_amount` (number,null)
    The outstanding balance to be settled in foreign currency after the event.

This field is mandatory for events created (event_created_at) from April 15, 2024 onwards, in cases of exchange operations with future settlement.
    Example: 678.57

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

  - `results.tev_amount_amount` (number,null)
    The "All-in Rate" (Valor Efetivo Total/Total Effective Cost), representing the total cost of the operation after the event. 

This field is required for spot exchange operations that reach up to the limit of $100,000 USD or equivalent in other currencies.
    Example: 1002

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

  - `results.local_currency_advance_percentage` (number,null)
    The percentage of the foreign currency value that was granted to the client in advance after the event.

This field is mandatory in cases of exchange operations with future settlement.
    Example: 0.12

  - `results.settlement_method` (string,null)
    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

  - `results.operation_category_code` (string,null)
    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"

  - `results.foreign_partie_relationship_code` (string,null)
    The code indicating the relationship between the customer and the foreign payer/receiver.

This code must comply with the relationship codes referenced in Resolution 277 or Circular 3690, as applicable to the exchange contract.

> Note: This field is optional when:
> - The settlement_method field is ESPECIE_CHEQUES_VIAGEM or CARTAO_PREPAGO.
> - The event_type field is different from 4 (Settlement of exchange operation in the primary market).
>
> If the institution has this information, it is mandatory to send it. If the information is updated after contracting, it must be sent through events.
    Example: "50"

  - `results.foreign_partie_name` (string,null)
    The name of the foreign payer or receiver.

> Note: This field is optional when:
> - The settlement_method field is ESPECIE_CHEQUES_VIAGEM or CARTAO_PREPAGO.
> - The event_type field is different from 4 (Settlement of exchange operation in the primary market).
>
> If the institution has this information, it is mandatory to send it. If the information is updated after contracting, it must be sent through events.
    Example: "Global Tech Imports LLC"

  - `results.foreign_partie_country_code` (string,null)
    The country code of the foreign payer or receiver, following the ISO 3166-1 standard.

> Note: This field is optional when:
> - The settlement_method field is ESPECIE_CHEQUES_VIAGEM or CARTAO_PREPAGO.
> - The event_type field is different from 4 (Settlement of exchange operation in the primary market).
>
> If the institution has this information, it is mandatory to send it. If the information is updated after contracting, it must be sent through events.
    Example: "US"

## 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 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

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


For not_found errors, the description is:

  - Not found
    Example: "Not found"

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

## Response 408 fields (application/json):

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


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

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


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

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

## Response 500 fields (application/json):

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


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

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


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

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