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

# Location inbound

# Tango Location Inbound API

> Generated from `Tango Location Inbound API Integration Design Specification V2.0.docx` in SharePoint folder `01 Common Integrations`.
> OAS spec: [`location-inbound.yaml`](./location-inbound.yaml)

## Overview

Async REST API: client inserts/updates Property / Building / Floor / Location-Store records in Tango. Single endpoint handles all four entity types — Tango disambiguates by which entity-type key fields are present in each record. Two-call pattern with `gu_id` polling.

**Owner:** Tango Analytics
**Spec version:** 2.0
**Status:** Draft (auto-generated — needs review). **Full field mapping was not extracted from source.**

## 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/locationmgmt/locations` | Insert/update location records (async). |
| GET | `/v1/batch/status?gu_id=...` | Poll processing status. |

## Integration logic

### Insert/update

* One of `store_id` / `store_number` must be present.
* If the identifier exists, the record is updated.
* If not, a new record is created.

### Brand resolution

* If `brand_id` is sent → used.
* If absent and the client has one brand → that brand is used.
* If absent and the client has multiple brands → error.

### Geo-coding

* `geo_code = Y` → Tango auto-populates `latitude` / `longitude` from the address fields.
* `geo_code = N` or null → Tango uses the provided coordinates or leaves them blank.
* When an address field changes, the client should pass `geo_code = Y` to trigger re-geocoding.

### Lookups

* For any dropdown / lookup field, only the codes documented in the Appendix are accepted.

## Required-field rules (from validations, since data-mapping table wasn't extractable)

| Field | When required |
| - | - |
| `store_id` OR `store_number` | Always (at least one) |
| `latitude` / `longitude` | When `geo_code = N`/null AND record is an INSERT |
| `status` | INSERT only |
| `country` | INSERT only AND `geo_code = Y`; must be ISO 3-char |
| `address` / `city` / `state` / `county` / `zip` | When `geo_code = Y` |
| `geo_code` | Must be `Y` or `N` if provided |

## Validations (per source doc — 26 listed)

Lookup-validation errors for `property_type`, `dev_type`, `facility_type`, `location_type`, `ownership_type`, `contractual_type`, `measurement_type`, `occupancy_status`, plus client-defined user-defined lookup fields. Date-format validations enforce `MM/DD/YYYY` on `purchase_date` / `open_date` / `close_date` and on any user-defined date fields.

If geocoding logic fails, returns `unable to retrieve coordinates`.

## Open Questions / Assumptions

* [ ] **Full field mapping not extracted from source** — the data-mapping table appears in the source doc but didn't surface in the text extraction (likely in a multi-page Word table that python-docx didn't capture cleanly). The schema lists only fields named in the validations and adds `additionalProperties: true` so unknown fields aren't rejected. A real consumer will need the full Tango Location field list.
* [ ] **Direction inconsistency**: source header `Source: TANGO / Destination: Client System` contradicts the description ("Insert/Update Property/Building/Store/Floor information in Tango"). Treated as inbound.
* [ ] **Custom extension attributes** (`c_ext_attr1..104`, `t_ext_attr4`, etc.) are referenced in the changelog but their full enumeration isn't in the extracted text.
* [ ] **No example request body** was extractable.

## Changelog (compressed)

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1–1.9 | 2022-2026 | (see source doc — many revisions over 4 years) | Various |
| 2.0 | 04/23/2026 | Updated API architecture diagram | Alpna Bansal |