> ## 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.

# Lookups inbound

# Tango Lookups Inbound API

> Generated from `Tango Lookups Inbound Integration Design Specification - API V0.8.docx` in SharePoint folder `01 Common Integrations`.
> OAS spec: [`lookups-inbound.yaml`](./lookups-inbound.yaml)

## Overview

Async REST API for posting custom-lookup dropdown values into Tango. Used to populate specific Tango custom lookups (`CLOV_*`) so client-defined values are available in dropdowns across Projects / Properties modules.

**Owner:** Tango Analytics
**Spec version:** 0.8
**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/batch/external-lookups` | Submit lookup values (async). |
| GET | `/v1/batch/status?gu_id=...` | Poll processing status. |

## Supported lookups

Only the following custom lookups can be loaded through this integration:

* `CLOV_COST_CENTER`
* `CLOV_INTERNAL_ORDER`
* `CLOV_PRODUCT_LIST`
* `CLOV_PROFIT_CENTER`

## Integration logic

* Upsert key: `(lookup_name, lookup_code)`. For multi-country clients, `country` is added to the key.
* Existing `(name, code)` combination → updates the other fields.
* New `(name, code)` combination → inserts a new lookup value.
* `status = ACTIVE` makes the value selectable in UI; any other status hides it.
* Duplicate records in a single payload → the latest entry wins.

## Data model (required ✅)

| Field | Type | Req | Sample | Notes |
| - | - | - | - | - |
| `lookup_name` | VARCHAR | ✅ | `CLOV_PROFIT_CENTER` | Must be a supported lookup |
| `lookup_code` | VARCHAR | ✅ | `BMC` | Part of upsert key |
| `lookup_value` | VARCHAR | ✅ | `Bulk Mail Center` | Display value |
| `lookup_desc` | VARCHAR | – | `Bulk Mail Center` | |
| `status` | VARCHAR | ✅ | `ACTIVE` | `ACTIVE` displays in UI; other = hidden |
| `country` | VARCHAR | conditional | `USA` | ISO 3-letter; required for multi-country clients |
| `sequence` | NUMBER | ✅ | `10` | Display order; whole numbers only |
| `ext_attr1` – `ext_attr16` | VARCHAR | – | | Custom extension attributes |

## Validations

1. `lookup_name` null → `lookup_name is missing or empty`
2. `lookup_name` does not exist → `lookup_name does not exist`
3. `lookup_code` null → `lookup_code is missing or empty`
4. `lookup_value` null → `lookup_value is missing or empty`
5. `status` null → `status is missing or empty`
6. `country` null → `country is missing or empty` (multi-country clients only)
7. `country` invalid → `country <> is invalid`
8. `sequence` not a number → `Sequence <> is invalid` (whole numbers only)

## Open Questions / Assumptions

* [ ] **Sample JSON has mixed case for `ext_attr*`** — one record uses `ext_attr1` (lowercase), another uses `Ext_Attr1` (PascalCase) within the same payload. Mapping table uses lowercase with internal space (`ext _Attr1`); preserved as lowercase no-space in the schema. Confirm wire format.
* [ ] **Sample JSON sends `sequence` as a string** (`"sequence": "10"`) but the mapping table types it as NUMBER. Schema uses number; consumers may need to coerce.
* [ ] **Error response includes `lookup_code`** as a top-level field within each error entry (in addition to `record_key`). This differs from other Tango APIs where errors only have `record_index` / `record_key` / `error`.
* [ ] **Missing comma** in the sample JSON between `"ext_attr6": ""` and `"ext_attr7": ""` is preserved in the source — that's a doc typo, not a wire format requirement.
* [ ] **Lookup-name expansion** — only 4 `CLOV_*` types are supported; if new ones are added, the integration logic section needs updating.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1 | 03/06/2025 | Initial Draft | Jasmin Thasleem |
| 0.2 | 03/07/2025 | Updated Data Mapping – Header | Jasmin Thasleem |
| 0.3 | 03/18/2025 | Updated Request body, Data Mapping, Validations | Jasmin Thasleem |
| 0.4 | 03/19/2025 | Added Response, Integration Status, Logic | Jasmin Thasleem |
| 0.5 | 03/24/2025 | Updated Integration Logic | Jasmin Thasleem |
| 0.6 | 03/28/2025 | Removed BU/Brand IDs; added Country | Rahma Ouedraogo |
| 0.7 | 04/04/2025 | Added Sequence | Rahma Ouedraogo |
| 0.8 | 04/23/2026 | Updated architecture diagram | Alpna Bansal |