> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tangoanalytics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Currency conversion api

# Tango Currency Conversion API

> Generated from `Tango Currency Conversion API Integration Design Specification V1.2.docx` in SharePoint folder `01 Common Integrations`.
> OAS spec: [`currency-conversion-api.yaml`](./currency-conversion-api.yaml)

## Overview

Async REST API for posting forex rate records to Tango. Each record carries a spot rate, an optional average rate, an "as of" date, and an effective-from/to window. Tango uses these rates for multi-currency translation across the Transaction → Country → BU → Global currency hierarchy.

**Owner:** Tango Analytics
**Spec version:** 1.2
**Status:** Draft (auto-generated — needs review)

## Base URLs

| Environment | URL |
| - | - |
| Production | `https://api.tangoanalytics.com` |
| Test (SIT/UAT) | `https://testapi.tangoanalytics.com` |

## Authentication

Headers `x-client` + `x-api-key`.

## Endpoints

| Method | Path | Summary |
| - | - | - |
| PUT | `/v1/common/exchangerates` | Submit forex rates (async). |
| GET | `/v1/batch/status?gu_id=...` | Poll processing status. |

## Currency hierarchy (per source doc)

| Tier | Description |
| - | - |
| **Transaction Currency** | Currency of a single payment / PO / etc. — lowest tier. |
| **Country Currency** | Common currency for a given country; used for in-country reporting. |
| **BU Currency** *(optional)* | Currency at the Business Unit level (combination of client countries). Defaults to USD. |
| **Global Currency** | USD. All currencies must have a USD-based conversion. |

## Out-of-scope

* Conversion to non-USD global currencies — client must provide USD-based ratios.
* In-house standard rates — Tango uses only the rates the client provides.

## Data model (required ✅)

| Field | Type | Req | Notes |
| - | - | - | - |
| `source_currency` | VARCHAR | ✅ | ISO 4217 3-letter code |
| `converted_currency` | VARCHAR | ✅ | ISO 4217 3-letter code |
| `spot_exchange_rate` | NUMBER | ✅ | Up to 38 decimal places |
| `avg_exchange_rate` | NUMBER | – | Used in payment / billing calculations |
| `exchange_rate_date` | DATE `MM/DD/YYYY` | ✅ | "As of" date |
| `effective_from` | DATE `MM/DD/YYYY` | ✅ | |
| `effective_to` | DATE `MM/DD/YYYY` | ✅ | |

## Validations

| # | Condition | Error message |
| - | - | - |
| 1 | `source_currency` missing | `required field: source_currency is missing or empty` |
| 2 | `converted_currency` missing | `required field: converted_currency is missing or empty` |
| 3 | `spot_exchange_rate` missing | `required field: spot_exchange_rate is missing or empty` |
| 4 | `exchange_rate_date` missing | `required field: exchange_rate_date is missing or empty` |
| 5 | Any date field not `MM/DD/YYYY` | `field <> value is not a valid date string` |

## Open Questions / Assumptions

* [ ] **`record_key` format** in error responses: doc shows both `"USD-GBP"` and `" USD-INR"` (note leading space). Whitespace handling on the wire should be confirmed.
* [ ] **Sample sends numeric fields as strings** (`"spot_exchange_rate": "5.1111"`). Schema uses `number`; consumers may need to coerce.
* [ ] **Rate frequency** is implied to be Daily / Monthly / Annual per assumptions, but the schema doesn't carry a frequency field. Effective-from/to provides the window.
* [ ] **Lookup codes** are `<TBD>` in Appendix.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1–1.1 | 2020-2023 | (see source doc) | Various |
| 1.2 | 04/23/2026 | Updated API architecture diagram | Alpna Bansal |