Vehicles¶

Vehicles provide a solicitation-centric way to discover groups of related IDVs and then expand into the underlying awards.

What is a Vehicle?¶

In Tango, a Vehicle is a grouping of multiple IDVs that share the same solicitation_identifier and the same awarding-agency identifier derived from the IDV award key.

In federal data, each IDV award is a vehicle. In practice, people often think of a “vehicle” as the solicitation that produced many IDV awards (one per awardee). We model that higher-level grouping explicitly.

Vehicles are useful when you want to:

• Find “the contract vehicle” behind a set of IDVs (e.g., the solicitation that produced a schedule/IDIQ vehicle)
• Search across a vehicle’s underlying IDVs
• Pull a shaped list of the IDVs that make up a vehicle

Endpoints¶

• List: GET /api/vehicles/
• Detail: GET /api/vehicles/{uuid}/
• Task Orders: GET /api/vehicles/{uuid}/orders/

Search¶

Vehicle-level search (list)¶

Use ?search= on the list endpoint to search vehicles:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/?search=GSA%20schedule&page=1"

Award-within-vehicle search (detail, when expanding awards)¶

On the detail endpoint, ?search= is used to filter expanded awardees (IDVs) when your shape includes awardees(...).

Ordering¶

The vehicles list endpoint supports ordering by activity metrics and statistics using the ?ordering= query parameter.

Available ordering fields¶

• vehicle_obligations - Total obligations across all IDVs in the vehicle
• latest_award_date - Most recent IDV award date in the vehicle

Ordering syntax¶

• Ascending: ?ordering=vehicle_obligations
• Descending: ?ordering=-vehicle_obligations (prefix with -)
• Multiple fields: ?ordering=-vehicle_obligations,-latest_award_date

Examples¶

Sort by total obligations (highest first):

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/?ordering=-vehicle_obligations&page=1"

Sort by most recent award activity:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/?ordering=-latest_award_date&page=1"

Sort by obligations, then by latest award date:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/?ordering=-vehicle_obligations,-latest_award_date&page=1"

Note: When no ?ordering= parameter is provided, vehicles are ordered by solicitation_identifier, agency_id, and uuid (default ordering).

Task Orders¶

The GET /api/vehicles/{uuid}/orders/ endpoint returns all task orders (contracts) issued against all IDVs within a vehicle. This endpoint supports pagination, response shaping, filtering, search, and transaction expansion, similar to the /api/contracts/ endpoint.

Basic usage¶

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?page=1"

Filtering¶

Filter task orders using the same filters available on /api/contracts/:

# Filter by date range
curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?award_date_gte=2024-01-01&award_date_lte=2024-12-31"

# Filter by recipient
curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?recipient=ACME"

Response shaping¶

Use the shape parameter to customize fields and expand related objects:

# Include recipient and transaction details
curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?shape=key,piid,award_date,recipient(display_name,uei),transactions(description,action_date,modification_number)"

Search¶

Search task order descriptions:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?search=software"

Ordering¶

The orders endpoint supports ordering by contract fields using the ?ordering= parameter:

• award_date - Contract award date (default: descending, newest first)
• obligated - Obligated amount
• potential_total_value - Total contract value
• recipient_name - Recipient legal business name

Default ordering: When no ?ordering= parameter is provided, task orders are ordered by -award_date, -uuid (newest first).

Examples:

# Default ordering (newest first)
curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?page=1"

# Order by obligated amount (highest first)
curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?ordering=-obligated&page=1"

# Order by recipient name
curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/orders/?ordering=recipient_name&page=1"

The response includes vehicle context in the metadata (vehicle UUID and solicitation identifier).

Response shaping¶

Vehicles support the shape parameter, including the awardees(...) expansion.

Example: fetch a vehicle with a shaped list of its IDVs:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/?shape=uuid,solicitation_identifier,organization_id,awardee_count,order_count,vehicle_obligations,vehicle_contracts_value,awardees(key,uuid,piid,award_date,recipient(display_name,uei))"

Example: include opportunity-derived fields and expand the linked Opportunity:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/?shape=uuid,solicitation_identifier,solicitation_title,solicitation_date,naics_code,opportunity(opportunity_id,title,first_notice_date,office(office_name,agency_name))"

Example: expand JSON detail fields to select specific sub-fields:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/?shape=uuid,solicitation_identifier,competition_details(extent_competed,number_of_offers_received),type_of_idc,contract_type"

Example: filter expanded awards within a vehicle:

curl -H "X-API-KEY: <key>" \
  "https://tango.makegov.com/api/vehicles/<vehicle-uuid>/?shape=uuid,awardees(key,uuid,recipient(display_name))&search=acme"

See Response Shaping for full syntax and flattening options.