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

# User roles reconcile bu

# Tango BU User Roles Reconcile API

> Generated from `Tango BU User Roles Reconcile API Integration Design Specification V0.9.docx` in SharePoint folder `01 Common Integrations`.
> OAS spec: [`user-roles-reconcile-bu.yaml`](./user-roles-reconcile-bu.yaml)

## Overview

Async **outbound** REST API: client retrieves Tango user accounts and their full provisioning state (brands, BUs, countries, roles, entity security) for reconciliation. Same endpoint as the inbound provisioning API (`/v1/usermgmt/batch/users`) but called via GET. Page size 1000.

**Owner:** Tango Analytics
**Spec version:** 0.9
**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 |
| - | - | - |
| GET | `/v1/usermgmt/batch/users` | Initiate user export — returns `gu_id`. |
| GET | `/v1/batch/status?gu_id=...&page_no=...` | Retrieve paginated records. |

## Filter parameters (mutually exclusive)

| Param | Notes |
| - | - |
| *(none)* | Returns all users. |
| `user_name` | Returns one specific user. |
| `status` | Returns users with the given status (`A` / `N`). |

Only one filter may be supplied per call.

## Integration logic

* Batch refresh runs **once per day** at a mutually-agreed time.
* The data API must be invoked **at most once per day** aligned with the refresh.
* Additional same-day calls generate a new `gu_id` but return no data.
* Status polling is unrestricted — the same `gu_id` may be polled multiple times.
* Page size is **1000** (smaller than other Tango outbound APIs which use 5000).

## Data model

Each user record carries:

* Identity: `user_name`, `first_name`, `last_name`, `email`
* Type / flags: `user_type`, `sso`, `status`, `mobile_access`
* Defaults: `default_brand`, `default_bu`, `default_country`, `default_language` (e.g., `en-US`), `data_access_level`
* Audit: `creation_date`, `created_by`, `last_login_date`, `last_update_date`, `last_updated_by`
* `entity_security[]`: per-BU / per-country / per-entity-type security with restrictions
* `brands[]`, `bu[]`, `country[]`, `roles[]`: nested audit-bearing structures

### Nested-object shape note ⚠

The source data mapping shows an unusual nesting for `brands` / `bu` / `country` / `roles`. Each item is an object whose **key is the field type label** (e.g., `brand_name`, `bu_name`, `country_name`) and whose value is an object with `name`, `creation_date`, `created_by`, `last_update_date`, `last_updated_by`:

```json theme={null}
{
  "brands": [
    {
      "brand_name": {
        "name": "TEST,OPS,RETAIL",
        "creation_date": "01/01/2024",
        "created_by": "integration",
        "last_update_date": "02/03/2024",
        "last_updated_by": "integration"
      }
    }
  ]
}
```

This is unusual; the wrapper key (`brand_name`) is functionally redundant. Preserved verbatim — confirm wire format.

## Open Questions / Assumptions

* [ ] **Once-per-day cadence enforcement**: how does the API behave if a client polls early? "Generate a new gu\_id but no data" suggests the call succeeds but returns empty — confirm error vs. empty-result behaviour.
* [ ] **Nested-key shape** (described above) is unusual. May be a copy-paste artifact in the doc; confirm whether the real JSON uses the wrapper key.
* [ ] **`entity_security.entity_type` values** listed include `TARGET`, `SITE`, `LEASE`, etc. — `TARGET` isn't documented elsewhere; confirm the full enum.
* [ ] **`roles[]` shape** truncated in the extracted text — the schema uses `additionalProperties: true` for now.
* [ ] **Page size 1000** is half the typical Tango page size — verify this is intentional for large tenants.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1–0.5 | 2022-2023 | (see source doc) | Various |
| 0.6 | 07/12/2024 | Added Creation/Update audit fields, Mobile Access, Last Log in | Rahma Ouedraogo |
| 0.7 | 03/03/2025 | Updated pagination size | Rahma Ouedraogo |
| 0.8 | 04/09/2026 | Updated integration logic | Jasmin Thasleem |
| 0.9 | 04/23/2026 | Updated API architecture diagram | Alpna Bansal |