Skip to content

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.

Budget flows (Beta): Federal accounts that paid this vendor, with surrounding account context and hydrated contracts: GET /api/entities/{uei}/budget-flows/. See Budget.

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 (address normalization now includes county, county_code, fips_code when available from DSBS), 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

Param What it does
search Search entities (name + aliases + other indexed fields).
uei Filter by UEI (exact, case-insensitive).
cage_code Filter by CAGE code (exact, case-insensitive).
name Filter by legal business name (substring match).

Location

Param What it does
state Filter by entity physical address state/province code.
zip_code Filter by ZIP code (exact).

Classification

Param What it does
naics Filter by NAICS.
psc Filter by PSC.
socioeconomic Filter by business type / socioeconomic code.

Other

Param What it does
purpose_of_registration_code Filter by purpose-of-registration code (when present).
total_awards_obligated_gte Filter entities with total obligated amount greater than or equal to a USD value.
total_awards_obligated_lte Filter entities with total obligated amount less than or equal to a USD value.

Multi-value filter syntax

Use | (or the literal word OR) to match any of several values:

socioeconomic=8A|WOSB

The same syntax works on every filter that accepts multiple values.

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

See also: Full SDK method reference — tango-python methods · tango-node methods.

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);
Report an issue with this page