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

# Invoice outbound api

# Tango Project Invoice Outbound API

> Generated from `Tango Project Invoice Outbound API Integration Design Specification V1.1.docx` in SharePoint folder `04 Projects Integrations`.
> OAS spec: [`invoice-outbound-api.yaml`](./invoice-outbound-api.yaml)

## Overview

Async REST API used by the client to fetch approved invoices from Tango. Two-call pattern: a GET against the invoices endpoint returns a `gu_id` immediately; a subsequent GET to the Status endpoint returns the full record set. The same `gu_id` can be polled multiple times to retrieve the same records.

**Owner:** Tango Analytics
**Spec version:** 1.1
**Status:** Draft (auto-generated from design doc — needs review)

## Base URLs

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

## Authentication

`x-client` and `x-api-key` headers, required on every call.

## Endpoints

| Method | Path | Summary |
| - | - | - |
| GET | `/v1/projectmgmt/batch/invoices` | Initiate invoice export — returns `gu_id`. |
| GET | `/v1/batch/status?gu_id=...` | Retrieve invoice records by `gu_id`. |

### `GET /v1/projectmgmt/batch/invoices`

**Response — 200 OK**

```json theme={null}
{
  "status": "OK/Error",
  "status_message": "",
  "gu_id": "721c54c4-c7aa-4fa1-8fdfd6-c0cee161694d"
}
```

On error the response omits `gu_id`.

### `GET /v1/batch/status?gu_id=...`

Returns the invoice records. Null fields in Tango are omitted from the response.

**Sample response (truncated)**

```json theme={null}
{
  "records": [
    {
      "inv_id": 1234,
      "inv_number": "1234",
      "inv_type": "REGULAR",
      "inv_date": "10/27/2022",
      "po_number": "394226",
      "project_number": "47089",
      "supplier_number": "S022",
      "supplier_site_number": "S022",
      "currency": "USD",
      "pct_inv_amt": 43343.44,
      "retainage_pct": 5,
      "status": "APPROVED",
      "final_invoice": "N",
      "details": [
        {
          "detail_id": 1234,
          "task_id": 2332,
          "seq_no": 10,
          "currency": "USD",
          "po_amount": 3333.34,
          "amount": 22222.00,
          "net_amount": 33333.90,
          "task_name": "Construction",
          "line_item_name": "Retainer Wall Construction",
          "division": "1000"
        }
      ]
    }
  ]
}
```

## Integration logic

* Only approved invoices are returned.
* After successful export the invoice is flagged `Exported` in Tango.
* A field with a null/unconfigured value is omitted from the JSON entirely (not sent as empty).
* The `gu_id` can be re-polled — the response is idempotent for a given `gu_id`.

## Data model — Invoice (header)

| Field | Type | Description |
| - | - | - |
| `inv_id` | NUMBER | Tango-generated unique invoice ID |
| `inv_number` | VARCHAR | Client-defined invoice number |
| `inv_type` | VARCHAR | `REGULAR` / `RETAINAGE` |
| `inv_date` | DATE (MM/DD/YYYY) | |
| `po_number` | VARCHAR | |
| `project_number` | VARCHAR | |
| `location_number` | VARCHAR | |
| `supplier_number` | VARCHAR | |
| `supplier_site_number` | VARCHAR | |
| `currency` | VARCHAR | ISO 4217 3-char |
| `pct_inv_amt` | NUMBER | |
| `exchange_rate` | NUMBER | |
| `payment_terms` | VARCHAR | |
| `retainage_pct` | NUMBER | |
| `status` | VARCHAR | |
| `submitted_by` | VARCHAR | |
| `approved_by` | VARCHAR | |
| `created_by` | VARCHAR | |
| `creation_date` | DATE | |
| `state` | VARCHAR | |
| `zip` | VARCHAR | |
| `final_invoice` | VARCHAR | Y/N |
| `details` | array | One or more `InvoiceDetail` |

## Data model — Invoice Detail

| Field | Type | Description |
| - | - | - |
| `detail_id` | NUMBER | Tango-generated |
| `task_id` | NUMBER | |
| `seq_no` | NUMBER | |
| `currency` | VARCHAR | ISO 3-char |
| `po_amount` | NUMBER | |
| `amount` | NUMBER | |
| `remaining_bal` | NUMBER | |
| `net_amount` | NUMBER | Rounded to 2 decimals |
| `retainage_pct` | NUMBER | |
| `tax_group` | VARCHAR | |
| `tax_rate` | NUMBER | |
| `vendor_tax` | NUMBER | Rounded to 2 decimals |
| `accrued_tax` | NUMBER | |
| `seg1` – `seg6` | VARCHAR | |
| `acct_code` | VARCHAR | |
| `comments` | VARCHAR | |
| `nattr1`, `nattr2` | VARCHAR | (Type appears mismatched — see Open Questions) |
| `task_name` | VARCHAR | |
| `line_item_name` | VARCHAR | |
| `division` | VARCHAR | |

## Open Questions / Assumptions

* [ ] **No `required` annotation** on outbound fields — the data-mapping table for this integration doesn't have a "Required?" column. Treating all as optional.
* [ ] **`nattr1`/`nattr2` type mismatch**: the sample JSON shows numeric values, but the mapping table lists them as VARCHAR. Schema mirrors the mapping table (VARCHAR); confirm.
* [ ] **`status` allowed values** are not enumerated; the example shows `APPROVED`.
* [ ] **`tax_group` allowed values** are not enumerated.
* [ ] **Pagination behavior**: the doc does not say whether the Status response is paginated for large batches (the Project Attributes API explicitly is — this one is silent).
* [ ] **No explicit error response shape** for the initial GET when it produces `status: "Error"`; modelled as the same envelope minus `gu_id`.

## Changelog

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1 | 4/2/2021 | Initial version | Michael Phoenix |
| 0.2 | 4/9/2021 | Updated Architecture and outbound structure | Shalmali Patil |
| 0.3 | 5/14/2021 | Updated API design and Data Mapping | Alpna Bansal |
| 0.4 | 07/18/2022 | Updated Request & Integration Status | Olivia Aneye |
| 0.5 | 09/02/2022 | Removed reviewers & updated formatting | Jasmin Thasleem |
| 0.6 | 11/22/2022 | Updated Integration Status | Jasmin Thasleem |
| 0.7 | 12/29/2022 | Updated Data Mapping (Client Label) | Jasmin Thasleem |
| 0.8 | 10/31/2023 | Reformatted sections, Updated JSON & Data Mapping | Jasmin Thasleem |
| 0.9 | 04/11/2025 | Added final\_invoice, line\_item\_seq, line\_item\_name, task\_name | Jasmin Thasleem |
| 1.0 | 07/21/2025 | Removed entity\_type | Jasmin Thasleem |
| 1.1 | 04/23/2026 | Updated API Architecture | Jasmin Thasleem |