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

# Store contacts inbound

# Tango Update Store Contacts API

> Generated from `Tango Update Store Contacts API Integration Design Specification V0.5.docx` in SharePoint folder `01 Common Integrations`.
> OAS spec: [`store-contacts-inbound.yaml`](./store-contacts-inbound.yaml)

## Overview

Async REST API: client inserts/updates contacts attached to a store in Tango. The store must already exist; this API doesn't create stores.

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

## Base URLs

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

## Authentication

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

## Endpoints

| Method | Path | Summary |
| - | - | - |
| PUT | `/v1/locationmgmt/locationcontacts` | Insert/update store contacts (async). |
| GET | `/v1/batch/status?gu_id=...` | Poll processing status. |

## Integration logic

* The store referenced by `store_number` must already exist in Tango; contact loads against missing stores fail.
* Upsert key: `(store_number, role)`. The same role cannot exist twice on the same store.
* Matching `(store_number, role)` → existing contact is updated.
* Non-matching → new contact is created.

## Data model (required ✅)

| Field | Type | Req | Notes |
| - | - | - | - |
| `store_number` | String | ✅ | Resolves to Tango's internal STORE\_ID; with `role` is the upsert key |
| `role` | String | ✅ | Must match `CONTACTS_ROLE` lookup |
| `first_name` | String | ✅ | |
| `last_name` | String | ✅ | |
| `company` | String | ✅ | |
| `business_phone` | String | – | |
| `extension` | String | – | |
| `email` | String | ✅ | |
| `fax` | String | – | |
| `status` | String | – | Expected `A` (Active) or `R` (Removed) |

## Validations

| # | Condition | Error message |
| - | - | - |
| 1 | `store_number` null | `store_number is missing or empty` |
| 2 | `store_number` not in Tango | `store_number does not exist` |
| 3 | `role` not in `CONTACTS_ROLE` lookup | `Invalid Lookup code: <role>` |

## Open Questions / Assumptions

* [ ] **Host URL is placeholder `<<hostname>>/<<context>>`** in source. Replaced with the standard Tango hosts as placeholders; confirm with the API team.
* [ ] **`status` allowed values**: source mentions `A` and `R`. Assumed `A` = Active and `R` = Removed; confirm.
* [ ] **No exception handling / Fall Back scenarios** — both sections are `<TBD>`.
* [ ] **Lookup codes** for `CONTACTS_ROLE` are `<TBD>` in Appendix.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1 | 07/26/2022 | Initial Draft | Alpna Bansal |
| 0.2 | 09/01/2022 | Updated formatting | Jasmin Thasleem |
| 0.3 | 11/01/2022 | Updated Integration Logic & Validations | Jasmin Thasleem |
| 0.4 | 01/16/2023 | Updated Data Mapping (Client Label) | Jasmin Thasleem |
| 0.5 | 04/23/2026 | Updated API architecture diagram | Alpna Bansal |