Quickstart - Tango Documentation

This guide walks you through a complete request / response cycle against the Contracts Inbound API — one of the simplest async integrations to start with. By the end you’ll have submitted a batch, polled its status, and parsed both the success and error shapes. The same pattern (auth headers + async submission + gu_id polling) applies to every REST API integration in this docs site, so what you learn here transfers directly to AP, AR, GL, Lease, Sales, and the rest.

Need SFTP file-based integration instead? Jump to the SFTP file delivery section at the bottom.

Prerequisites

Get your API credentials

Contact your Tango onboarding lead to request a client identifier and API key. You’ll receive two values:

x-client — a string identifying your client.
x-api-key — a secret bound to that client.

Both are needed on every request. Keep x-api-key in a secret manager, never in source control.

The test (testapi.tangoanalytics.com) and production (api.tangoanalytics.com) keys are different. Don’t reuse the same value across environments.

Confirm a supplier site exists

The Contracts Inbound API upserts on the key (supplier_site_number, contract_number). Your supplier_site_number must already exist in Tango — if it doesn’t, submission will fail with supplier_site_number does not exist.Ask your Tango onboarding lead which supplier site numbers are pre-loaded in your test environment, or pick one from the data your team has already migrated.

Pick an environment

Use the test environment for everything in this guide:

export TANGO_BASE="https://testapi.tangoanalytics.com"
export TANGO_CLIENT="<your-x-client-value>"
export TANGO_API_KEY="<your-x-api-key-value>"

For production, swap the base URL to https://api.tangoanalytics.com and the credentials to your prod values.

Submit your first batch

The Contracts Inbound endpoint accepts a JSON body with a records array. The minimum required fields per record are: contract_number, contract_name, supplier_site_number, contract_start_date, contract_end_date, contract_amount.

curl -X PUT "$TANGO_BASE/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": "QUICKSTART-001",
        "contract_name": "Quickstart Demo Contract",
        "supplier_site_number": "670234-1",
        "contract_start_date": "06/11/2013",
        "contract_end_date": "03/20/2026",
        "contract_amount": 5000000,
        "modification_amount": 70241015.18,
        "contract_status": "A"
      }
    ]
  }'

import os, requests

base    = os.environ["TANGO_BASE"]
headers = {
    "x-client":     os.environ["TANGO_CLIENT"],
    "x-api-key":    os.environ["TANGO_API_KEY"],
    "Content-Type": "application/json",
}

payload = {
    "records": [
        {
            "contract_number":      "QUICKSTART-001",
            "contract_name":        "Quickstart Demo Contract",
            "supplier_site_number": "670234-1",
            "contract_start_date":  "06/11/2013",
            "contract_end_date":    "03/20/2026",
            "contract_amount":      5_000_000,
            "modification_amount":  70_241_015.18,
            "contract_status":      "A",
        }
    ]
}

r = requests.put(f"{base}/v1/suppliermgmt/batch/agreements",
                 headers=headers, json=payload, timeout=30)
r.raise_for_status()
gu_id = r.json()["gu_id"]
print("Submitted; gu_id =", gu_id)

import fetch from "node-fetch";

const base = process.env.TANGO_BASE;
const headers = {
  "x-client":     process.env.TANGO_CLIENT,
  "x-api-key":    process.env.TANGO_API_KEY,
  "Content-Type": "application/json",
};

const payload = {
  records: [{
    contract_number:      "QUICKSTART-001",
    contract_name:        "Quickstart Demo Contract",
    supplier_site_number: "670234-1",
    contract_start_date:  "06/11/2013",
    contract_end_date:    "03/20/2026",
    contract_amount:      5_000_000,
    modification_amount:  70_241_015.18,
    contract_status:      "A",
  }],
};

const res = await fetch(`${base}/v1/suppliermgmt/batch/agreements`, {
  method:  "PUT",
  headers,
  body:    JSON.stringify(payload),
});
const { gu_id } = await res.json();
console.log("Submitted; gu_id =", gu_id);

You’ll get back an immediate acknowledgement:

{
  "status": "OK",
  "status_message": "",
  "gu_id": "721c54c4-c7aa-4fa1-8fdfd6-c0cee161694d"
}

Hang onto that gu_id — you’ll use it in the next step. It uniquely identifies the batch and can be polled repeatedly. If you lose it you cannot retrieve the result; you’d need to resubmit (which would also overwrite, since the upsert key is (supplier_site_number, contract_number)).

Poll for status

Tango processes the batch asynchronously. Hit the shared status endpoint until you get a terminal state (COMPLETED or ERROR):

curl "$TANGO_BASE/v1/batch/status?gu_id=$GU_ID" \
  -H "x-client: $TANGO_CLIENT" \
  -H "x-api-key: $TANGO_API_KEY"

import time, requests

while True:
    r = requests.get(f"{base}/v1/batch/status",
                     params={"gu_id": gu_id},
                     headers=headers, timeout=30)
    body = r.json()
    print(body)
    if body["status"] != "PROCESSING":
        break
    time.sleep(10)

async function pollUntilDone(guid) {
  while (true) {
    const res  = await fetch(`${base}/v1/batch/status?gu_id=${guid}`, { headers });
    const body = await res.json();
    console.log(body);
    if (body.status !== "PROCESSING") return body;
    await new Promise(r => setTimeout(r, 10_000));
  }
}
const finalResult = await pollUntilDone(gu_id);

You’ll see one of three response shapes, in this order:

PROCESSING
COMPLETED
ERROR (partial)

{ "status": "PROCESSING" }

Keep polling. There’s no time guarantee — small batches typically clear within seconds; multi-thousand-record submissions can take a few minutes.

{
  "status": "COMPLETED",
  "total_records": 1,
  "errors": null
}

All records were applied. You’re done.

{
  "status": "ERROR",
  "total_records": 1,
  "errors": [
    {
      "record_index": 0,
      "record_key": "QUICKSTART-001",
      "error": "supplier_site_number does not exist"
    }
  ]
}

Some (or all) records failed validation. The errors array has one entry per failed record, with record_index pointing back to the position in your original records array and error containing a comma-separated list of error messages for that record.Records that aren’t listed in errors succeeded.

Polling cadence. Start at 5–10 seconds, back off to 30–60 seconds after a minute, and cap at 2 minutes. Don’t poll faster than every 5 seconds; it doesn’t make the batch finish sooner.

Handle errors properly

A few error patterns to watch for:

HTTP 401 / 403 on submission

Your x-client / x-api-key headers are missing, mistyped, or don’t have access to the endpoint. Verify both values and confirm with Tango that your client has the right permissions enabled.

HTTP 400 with `status: Error` on submission

The submission itself was rejected before queueing — usually a malformed JSON body or a content-type mismatch. The status_message field will tell you which. A gu_id is NOT returned for these.

`status: ERROR` on status poll with empty errors[]

Tango couldn’t process the batch at all (rare). Check status_message for context; resubmit the batch.

Per-record validation failures

See the Validations table in the per-integration .md reference for the full list of error messages. Common ones:

<field> is missing or empty — required field omitted.
<field> does not match expected format — usually a date in something other than MM/DD/YYYY.
supplier_site_number does not exist — referenced an unknown entity.
<field> does not match lookup value — sent a value outside the configured lookup set.

Where to go next

Browse all integrations

See every available integration grouped by domain.

API reference

The full OpenAPI 3.1 spec catalogue.

Async patterns deep dive

More on gu_id, pagination, retries, and idempotency.

Field conventions

Date formats, null-omission rules, currency handling.

Alternative: SFTP file delivery

If you’re integrating via SFTP files instead of REST APIs, the flow is different but simpler:

Get SFTP credentials

Tango will provision a username + password (or SSH key) for the relevant SFTP host:

Production: sftp.tangoanalytics.com
Test (SIT/UAT): sftpdev.tangoanalytics.com

Drop a pipe-delimited `.txt` file

Use the integration’s documented path and naming pattern, e.g.:

/inbound/ap/MyClient_apin_20260515093000.txt

Body is one record per line, fields separated by |. See the integration’s .md reference for the exact column order.

Wait for Tango to consume the file

Tango’s batch program picks up files on a pre-agreed schedule. Once consumed, the file moves to a Processed/ subfolder with a timestamp suffix. Any errors are written to a service log and emailed to the configured contact.

Most file-based integrations have a REST API counterpart that’s preferred for new work. Check the integrations list to see which mode is appropriate for your use case.

​Prerequisites

​Submit your first batch

​Poll for status

​Handle errors properly

​Where to go next

Browse all integrations

API reference

Async patterns deep dive

Field conventions

​Alternative: SFTP file delivery

Prerequisites

Submit your first batch

Poll for status

Handle errors properly

Where to go next

Alternative: SFTP file delivery