Entities¶

Entities are vendors/recipients exposed at /api/entities/ (UEI is canonical). For field definitions, see the Entities Data Dictionary.

Endpoints¶

• GET /api/entities/ (list + filtering + search)
• GET /api/entities/{uei}/ (detail; UEI lookup is case-insensitive)

Related “scoped” list endpoints (awards for an entity):

• GET /api/entities/{uei}/contracts/
• GET /api/entities/{uei}/idvs/
• GET /api/entities/{uei}/otas/
• GET /api/entities/{uei}/otidvs/
• GET /api/entities/{uei}/subawards/

Metrics: Time-series obligation/award metrics for an entity: GET /api/entities/{uei}/metrics/<months>/<period_grouping>/. See Metrics for parameters and behavior.

Response Shaping¶

Entities default to the shaping pipeline — all responses go through shaping even without ?shape=. Use ?shape= to customize which fields are returned.

• List default: uei, legal_business_name, dba_name, entity_url, cage_code, business_types(*), sba_business_types(*), primary_naics, physical_address(*), purpose_of_registration(*), relationships(*)
• Detail default: All list fields plus display_name, uuid, dodaac, description, email_address, capabilities, congressional_district, keywords, registered, registration_status, federal_obligations(*), naics_codes(*), psc_codes, highest_owner(*), immediate_owner(*), mailing_address(*), all date fields, and structured code/description expands: entity_structure(*), entity_type(*), profit_structure(*), organization_structure(*), state_of_incorporation(*), country_of_incorporation(*).
• On-demand expand: past_performance(*) — aggregated contract history with summary and top_agencies. Accepts [top=N] bracket param (default 5, max 100). Example: ?shape=uei,past_performance[top=10](*).

Complex fields are normalized by the shaping pipeline: address keys are always snake_case, business_types and sba_business_types are always [{code, description, ...}] arrays, naics_codes are always [{code, sba_small_business}] objects, and code/description pairs (entity_structure, purpose_of_registration, etc.) are always {code, description} objects with map-based description fallback.

See Response Shaping for full syntax and the Entities Data Dictionary for field definitions.

Filtering¶

Swagger is the canonical list of query parameters. These are the core filters most people use day-to-day.

Identity / text search¶

Location¶

Classification¶

Other¶

Filter value syntax (AND / OR)¶

Some filters support basic boolean syntax:

• Use | or OR for OR
• Use , or AND for AND

Example: socioeconomic=8A|WOSB

Ordering¶

/api/entities/ does not currently support ordering=....

If you send ?ordering=... anyway, Tango returns HTTP 400 (ordering is opt-in per endpoint).

Pagination¶

Entities use standard page-number pagination:

• page (default 1)
• limit (max 100)

SDK examples¶

List entities (search + filters + shaping)¶

import os

from tango import ShapeConfig, TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])

resp = client.list_entities(
    search="acme",
    state="VA",
    naics="541511",
    limit=10,
    shape=ShapeConfig.ENTITIES_MINIMAL,
)

for e in resp.results:
    print(e.uei, e.legal_business_name)

import { ShapeConfig, TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });

const resp = await client.listEntities({
  search: "acme",
  state: "VA",
  naics: "541511",
  limit: 10,
  shape: ShapeConfig.ENTITIES_MINIMAL,
});

for (const e of resp.results) {
  console.log(e.uei, e.legal_business_name);
}

Get an entity (detail)¶

import os

from tango import ShapeConfig, TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])

entity = client.get_entity(
    "ZQGGHJH74DW7",
    shape=ShapeConfig.ENTITIES_COMPREHENSIVE,
)

print(entity.uei, entity.legal_business_name)

import { ShapeConfig, TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });

const entity = await client.getEntity("ZQGGHJH74DW7", {
  shape: ShapeConfig.ENTITIES_COMPREHENSIVE,
});

console.log(entity.uei, entity.legal_business_name);