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

# Overview

> Integrate your systems with Tango's lease, project, and financial data through REST APIs and SFTP file drops.

Tango Analytics exposes a set of integrations that let your client systems read from and write to Tango's lease, project, and finance modules. Every integration falls into one of two delivery styles — **REST API** or **SFTP file** — and shares a small number of common patterns described below.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Send your first request to Tango in under five minutes — an end-to-end example with authentication, submission, and status polling.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Browse the per-integration OpenAPI 3.1 specs with request/response schemas, parameters, and example payloads.
  </Card>
</CardGroup>

## Integration domains

Pick the area that matches what you're integrating. Each integration page links to its OpenAPI spec and a Markdown reference (validations, field tables, edge cases).

<CardGroup cols={2}>
  <Card title="Lease integrations" icon="building" href="/integrations/lease">
    Accounts Payable & Receivable, GL accruals, lease attributes, sales / percent rent, CPI indices, and lease invoices. Covers the day-to-day data that moves between your ERP and Tango's Lease module.
  </Card>

  <Card title="Projects integrations" icon="briefcase" href="/integrations/projects">
    Purchase Orders, Change Orders, Project Invoices, Contracts, Project Attributes, and Total Approved Budgets. Drives the cost-management side of Tango's Projects module.
  </Card>
</CardGroup>

## Two delivery styles

<Tabs>
  <Tab title="REST API (async)">
    Most modern Tango integrations are async REST APIs over HTTPS. Submission returns a `gu_id` immediately, and the client polls a shared `/v1/batch/status` endpoint to track processing.

    ```bash theme={null}
    # 1. Submit
    curl -X PUT https://api.tangoanalytics.com/v1/suppliermgmt/batch/agreements \
      -H "x-client: $TANGO_CLIENT" \
      -H "x-api-key: $TANGO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "records": [ { "contract_number": "...", "...": "..." } ] }'

    # 2. Poll
    curl https://api.tangoanalytics.com/v1/batch/status?gu_id=<id-from-step-1> \
      -H "x-client: $TANGO_CLIENT" \
      -H "x-api-key: $TANGO_API_KEY"
    ```

    <Info>
      **Why async?** Most batch payloads contain thousands of records. Synchronous processing would hold the HTTP connection open for minutes; instead Tango queues the work, returns a `gu_id` instantly, and lets your code poll on its own schedule.
    </Info>
  </Tab>

  <Tab title="SFTP file drop">
    The legacy delivery mechanism. Files are pipe-delimited text (`.txt`) with a fixed naming convention like `{ClientName}_apout_MMDDYYYYHHMMSS.txt`.

    ```text theme={null}
    # File path layout
    sftp.tangoanalytics.com:/outbound/ap/        # Tango -> client (e.g. AP, AR, GL, PO, CO)
    sftp.tangoanalytics.com:/inbound/ap/         # Client -> Tango
    sftp.tangoanalytics.com:/<dir>/Processed/    # Files Tango has already consumed
    ```

    <Note>
      Tango moves picked-up files to a `Processed/` subfolder with a timestamp suffix once it has consumed them — check there if a file seems to have "disappeared" after delivery.
    </Note>
  </Tab>
</Tabs>

## Common patterns

<AccordionGroup>
  <Accordion title="Authentication" icon="key">
    Every REST API call requires two headers:

    | Header | Purpose |
    | - | - |
    | `x-client` | Your Tango-issued client identifier. |
    | `x-api-key` | Your Tango-issued API key. |

    For SFTP integrations, you'll receive a per-environment SFTP username and password (or a public-key fingerprint to register). Contact your Tango onboarding lead to request credentials.

    <Warning>
      Never check `x-api-key`, SFTP passwords, or credentials into source control. Use a secret manager and inject them at runtime.
    </Warning>
  </Accordion>

  <Accordion title="Async submission — \`gu\_id\` polling" icon="clock">
    Submission endpoints (PUT/POST and most GETs) return immediately with a `gu_id`. To retrieve the final result you call `/v1/batch/status` (or `/v1batch/status` on a couple of legacy integrations — check the per-integration spec):

    ```json theme={null}
    // PROCESSING (keep polling)
    { "status": "PROCESSING" }

    // COMPLETED (all records OK)
    { "status": "COMPLETED", "total_records": 42, "errors": null }

    // ERROR (per-record details)
    {
      "status": "ERROR",
      "total_records": 10,
      "errors": [
        { "record_index": 1, "record_key": "INV-001", "error": "required field: x is missing or empty" }
      ]
    }
    ```

    Recommended polling cadence: 5–30 seconds initially, backing off to 1–2 minutes for long-running batches.
  </Accordion>

  <Accordion title="Pagination on outbound APIs" icon="pages">
    GET-style outbound integrations (AP Outbound, AR Outbound, GL, Lease Invoices, Lease Outbound) return data in pages of **5000 records**. The status response carries pagination metadata:

    ```json theme={null}
    {
      "status": "COMPLETED",
      "total_records": 40670,
      "total_pages": 9,
      "page_size": 5000,
      "page_no": 2,
      "records": [ /* ... */ ]
    }
    ```

    Pass `?page_no=N` to fetch a specific page; the same `gu_id` can be polled across pages and re-polled later.
  </Accordion>

  <Accordion title="Field omission convention" icon="eye-off">
    For outbound APIs, **any field that is null or unconfigured in Tango is omitted entirely from the JSON** — you will not see `"field": null` or `"field": ""`. Your client code must treat the absence of a key as "no value".

    For inbound payloads, you may either omit optional fields or send them as empty strings; both are accepted.
  </Accordion>

  <Accordion title="Date format" icon="calendar">
    Tango uses literal `MM/DD/YYYY` strings (e.g. `"06/11/2013"`) for date fields — **not** ISO 8601. This is documented per-field in each spec but is consistent across integrations.

    Datetime values that include a time component (rare) use the same date prefix plus a 24-hour time component.
  </Accordion>

  <Accordion title="Environments" icon="server">
    Every REST API has two base URLs:

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

    SFTP follows the same split: `sftp.tangoanalytics.com` for production, `sftpdev.tangoanalytics.com` for SIT/UAT. The path layout (e.g. `/outbound/ap`) is identical between environments.
  </Accordion>
</AccordionGroup>

## What's in each integration's reference

Every integration ships two documents in this docs site:

* A **`.yaml`** OpenAPI 3.1 spec — machine-readable, suitable for code generation, Postman import, and Spectral linting.
* A **`.md`** companion — human-readable summary with transport details, integration logic, the validations table, and an "Open Questions" section listing anywhere the source design doc was silent or ambiguous.

<Tip>
  The Open Questions section in each Markdown is intentional — it surfaces inferences the documentation tooling made when the source was incomplete. Treat each item as something to confirm with the integration owner before going live.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Start the quickstart" icon="play" href="/quickstart">
    Walk through a complete request/response cycle in under five minutes.
  </Card>

  <Card title="Browse all integrations" icon="list" href="/integrations">
    See every integration grouped by domain (Lease vs Projects) and by direction (inbound vs outbound).
  </Card>
</CardGroup>