API reference

Get a key

An API key comes with the Capture and Enterprise plans. Open Account in the app, find API access and press Create a key.

The key is shown once, so copy it then. Making a new key stops the old one, and so does changing your password.

A key belongs to the person who made it. It reads what that person can read, on the account they are working in.

Send the key

Send the key in a header named x-lawd-key on every request.

The API is read only. A key may send a GET and nothing else: anything that would add, change or remove something is refused.

x-lawd-key: YOUR_KEY

A first request

Every address below is added to your base address, which is shown beside your key on the Account screen. Answers are JSON.

Ask for /api with your key to get this whole description as JSON, with the limits of your own plan.

Written with BASE where your base address goes:

curl -H "x-lawd-key: YOUR_KEY" "BASE/awards?naics=332710&state=FL&per_page=25"

Pages and order

A list answers with total, rows and capped. per_page sets how many rows come back, from 1 to 200, and page moves through them, counted from 1.

sort names what to order by and dir is asc or desc. Each list says which values sort takes.

One search returns up to the number of rows your plan allows. total is counted up to that number. When more matched, capped holds the number you can page through; otherwise it is empty.

A filter that takes a list takes values separated by commas.

Errors

An error is JSON with three parts: code, a short name; message, one plain sentence; and data, which holds the status.

401 means the key is missing or is not recognised. 403 means the request is not allowed: it was not a GET, or the plan does not open that list. 404 means there is no such record. 429 means the key has asked too often.

When the service is busy an answer can leave out an optional part. It says which under skipped. Ask again to get it.

{"code":"lawd_not_found","message":"Award not found.","data":{"status":404}}

Asking too often

A key may ask a generous number of times a minute and a day, more than a script reading the record needs.

Past that the answer is 429, with a Retry-After header that says how many seconds to wait. Wait that long and ask again. Nothing is lost.

Notices

GET /opps

Contract notices on record, open and past, newest first.

Parameters

• q text
  Words in the title or the description.
• naics list
  NAICS codes, separated by commas. A code of fewer than six digits matches every code that starts with it.
• psc list
  Product or service codes, separated by commas. A shorter code matches every code that starts with it.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• buyer text
  Part of the name of a buying office or sub-agency.
• set_aside list
  Set-aside codes, separated by commas, as /set-asides lists them. ANY_SB means any small business set-aside.
• ntype list
  Kinds of notice, separated by commas, in the source's own words: Solicitation, Sources Sought, Presolicitation, Award Notice.
• category text
  One kind of work, as the record sorts notices: the same values the category field holds.
• active choice
  1 for notices still open, 0 for notices that have closed.
• from date
  Posted on or after this date, as YYYY-MM-DD.
• to date
  Posted on or before this date, as YYYY-MM-DD.
• deadline_from date
  Offers due on or after this date.
• deadline_to date
  Offers due on or before this date.
• entity whole number
  The company an award notice names, as a company id.
• watch_only switch
  Send 1 to keep only what your own watches match.
• sort choice
  What to order by: posted, deadline, title, buyer, naics, amount. Left out, it is posted.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id notice_id title sol_number dept subtier office posted ntype base_type naics psc set_aside set_aside_code deadline active pop_city pop_state award_date award_amount awardee_name entity_id ui_link category ai_fit desc_fetched has_brief

Beside the rows: total capped facets closing_7 new_7

Example

GET /opps?naics=332710&active=1&sort=deadline&dir=asc

GET /opps/{id}

One notice: its text, links and contacts, what the same office paid last time, and what it became.

Parameters

• id in the address
  The id of the notice, or its notice_id.

The answer holds

id notice_id title sol_number org_path dept subtier office posted posted_at archive_date archive_type notice_status ntype base_type naics psc set_aside set_aside_code deadline prev_deadline amended_at amendments active archived pop_city pop_state pop_zip pop_country pop_street office_city office_state office_zip office_country addl_info_link named_links award_date award_amount award_number awardee_name awardee_uei entity_id description desc_fetched ui_link links pocs ai_brief ai_json ai_fit category tags source created_at updated_at sam_url naics_title psc_title bkey last_time related office_vehicles office_people became lead_time watched pipeline rules budget labor

Some of the time: band entry forecast interest documents

Example

GET /opps/48213

GET /meaning/search

Open notices, or contracts ending, found from a description of the work: the codes and the words read from it, and each row with why it was found.

Parameters

• text text
  What the company does, in a sentence or a paragraph of three letters or more. Not needed when fits is sent.
• fits switch
  Send 1 to read the codes off the company record of your own account, and leave text out.
• kind choice
  opps for open notices, recompetes for contracts ending. Left out, it is opps.
• drop list
  What to leave out of what was read, separated by commas, each written as the answer writes it under read: naics:332710, psc:4820 or word:valve.
• naics list
  NAICS codes, separated by commas: only what was read inside them is looked for.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• set_aside list
  Set-aside codes, separated by commas, as /set-asides lists them. ANY_SB means any small business set-aside.
• page whole number
  Which page, counted from 1. A page holds 25 rows.

Each row under rows holds

id notice_id title sol_number subtier office posted ntype naics psc set_aside_code deadline active pop_city pop_state match fit

Beside the rows: total page per_page seen more cut capped notes kind text read

These are the fields of an open notice. With kind=recompetes a row holds: id award_id end_date months_out entity_id recipient_name naics psc awarding_sub awarding_office amount set_aside_code pop_state score match fit.

Example

GET /meaning/search?text=We%20overhaul%20hydraulic%20actuators&kind=recompetes

GET /meaning/like/{id}

Other open notices and contracts ending that share the codes and the words of one notice.

Parameters

• id in the address
  The id of the notice.

The answer holds

id naics read notices notices_total recompetes recompetes_total cut says

Example

GET /meaning/like/48213

Awards

GET /awards

Contract awards on record, newest first.

Parameters

• q text
  Words in the description or the company name.
• naics list
  NAICS codes, separated by commas. A code of fewer than six digits matches every code that starts with it.
• psc list
  Product or service codes, separated by commas. A shorter code matches every code that starts with it.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• rec_state list
  Two-letter state codes, separated by commas: where the winner is registered.
• buyer text
  Part of the name of a buying office or sub-agency.
• agency text
  Part of the name of an agency.
• recipient text
  Part of the name of the company that won.
• entity whole number
  The company that won, as a company id.
• uei text
  One registration of a company, by its Unique Entity ID.
• set_aside list
  Set-aside codes, separated by commas, as /set-asides lists them. ANY_SB means any small business set-aside.
• competed text
  Part of the extent competed, in the record's own words.
• category text
  One kind of work, as the record sorts awards: the same values the category field holds.
• from date
  Started on or after this date, as YYYY-MM-DD.
• to date
  Started on or before this date, as YYYY-MM-DD.
• fy whole number
  One federal fiscal year.
• min number
  Obligated dollars of at least this.
• max number
  Obligated dollars of at most this.
• offers choice
  How many offers the buyer received: 1, 2-4, 5+, any (the number is on record) or none (it is not).
• watch_only switch
  Send 1 to keep only what your own watches match.
• sort choice
  What to order by: date, amount, end, recipient, buyer, naics. Left out, it is date, the start date.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id source gen_id piid recipient_name recipient_uei entity_id awarding_agency awarding_sub awarding_office naics psc psc_desc description amount base_all_options start_date end_date potential_end_date pop_city pop_state rec_state set_aside_code extent_competed offers award_type category detail_fetched fy

Beside the rows: total capped sum sum_capped facets

Example

GET /awards?naics=332710&state=FL&per_page=25

GET /awards/{id}

One award: every field on record, its changes over time, its subawards and the notice it came from.

Parameters

• id in the address
  The id of the award.

The answer holds

id source gen_id piid parent_piid recipient_name recipient_uei recipient_cage entity_id awarding_agency awarding_sub awarding_office funding_agency funding_sub naics naics_desc psc psc_desc description amount base_all_options base_exercised subaward_count subaward_total sub_plan sole_authority start_date end_date potential_end_date date_signed last_modified pop_city pop_state pop_zip pop_county withdrawn pop_country rec_city rec_state rec_zip rec_country set_aside set_aside_code extent_competed offers solicitation_id award_type idv_type pricing_type category tags detail_fetched parent_gen_id idv_kids idv_kids_total tx_fetched fy created_at updated_at naics_title usaspending_url award_search_url bkey recompete same_buyer_recent pipeline history vehicle vehicle_row subawards notice band ot

Example

GET /awards/901245

GET /recompetes

Contracts whose period of performance ends soon, each with a score and the reasons for it.

Parameters

• months whole number
  How many months ahead to look, up to what your plan reaches. Left out, it is 12.
• naics list
  NAICS codes, separated by commas.
• psc list
  Product or service codes, separated by commas.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• buyer text
  Part of the name of a buying office or sub-agency.
• agency text
  Part of the name of an agency.
• q text
  Words in the description of the contract or in the name of the company that holds it.
• entity whole number
  The company that holds the contract, as a company id.
• recipient text
  Part of the name of the company that holds the contract.
• set_aside list
  Set-aside codes, separated by commas, as /set-asides lists them. ANY_SB means any small business set-aside.
• min number
  Obligated dollars of at least this.
• max number
  Obligated dollars of at most this.
• offers choice
  How many offers the buyer received: 1, 2-4, 5+, any (the number is on record) or none (it is not).
• watch_only switch
  Send 1 to keep only what your own watches match.
• sort choice
  What to order by: end, amount, score, recipient, buyer, recurs, field. Left out, it is end, with the soonest end date first.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id award_id end_date potential_end months_out entity_id recipient_name naics psc bkey awarding_sub awarding_office amount base_all_options set_aside_code extent_competed offers pop_state score signals recur_years recur_n mkt_vendors why updated_at description piid gen_id source

Some of the time: score_market yours

Beside the rows: total capped months sum

Example

GET /recompetes?naics=332710&months=18&sort=score

Companies

GET /entities

Companies that have won federal awards, the largest first.

Parameters

• q text
  Part of a company name, or a whole Unique Entity ID or CAGE code.
• state list
  Two-letter state codes, separated by commas: where the company is.
• naics list
  NAICS codes, separated by commas: companies with an award in any of them.
• buyer text
  Part of the name of an office or sub-agency the company has won at.
• sam switch
  Send 1 for companies with a registration on file.
• sb switch
  Send 1 for companies the record marks as small business of any kind.
• recent switch
  Send 1 for companies seen in the last two years.
• sort choice
  What to order by: total, count, name, last. Left out, it is total, the dollars won.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id name uei cage city state primary_naics sam_registered awards_count awards_total first_seen last_seen sb_flags

Beside the rows: total capped answer

Example

GET /entities?naics=332710&state=FL&sort=count

GET /entities/{id}

One company: its registrations, where it wins, its recent awards and the contracts it holds that end soon.

Parameters

• id in the address
  The id of the company.

The answer holds

id name norm uei cage duns parent_name city state zip primary_naics naics_list sb_flags sam_registered sam_status website awards_count awards_total opps_won first_seen last_seen merged_into verified notes sba_certs cert_8a_exit integrity_count integrity_last integrity_checked pocs_checked proceedings_q created_at updated_at aliases registrations by_fy buyers naics_mix psc_mix states set_asides subawards recent recompetes notices_won integrity cert_risk avg_award sam_url ahead watched vehicles labor jna exclusions exclusions_checked is_you meet tracked read by_office kin reg ot

Example

GET /entities/3310

GET /sec/companies

Companies on record that are matched to a filer at the SEC, each with its ticker, its industry, its latest annual revenue and its awards.

Parameters

• q text
  Part of a company name or of an industry, or a whole ticker.
• sort choice
  What to order by: name, ticker, industry, revenue or awards. Left out, it is revenue.
• dir choice
  asc or desc. Left out, it is desc for revenue and awards and asc for the others.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 100. Left out, it is 50.

Each row under rows holds

cik sec_name ticker exchange industry revenue rev_fy basis entity_id name state awards_total awards_count sure

Beside the rows: on_file total page per_page more sort dir slow failed q

Example

GET /sec/companies?q=aerospace&sort=awards

GET /sec/company/{id}

What one company has filed with the SEC: its ticker, its revenue and net income by year beside its awards, and its latest filings.

Parameters

• id in the address
  The id of the company, as /entities returns it.

The answer holds

on_file matched

Some of the time: says cik sec_name matched_name our_name ticker tickers exchange exchanges sic industry fye inc_state basis via sure years years_missing fed_known years_differ filings no_figures read_on

A company that is not matched to a filer answers on_file and matched alone. The rest are there when matched is true.

Example

GET /sec/company/3310

Buying offices and agencies

GET /buyers

Buying offices that have made awards, the largest first.

Parameters

• q text
  Part of the name of an office, a sub-agency or an agency.
• agency text
  Part of the name of an agency.
• naics list
  NAICS codes, separated by commas: offices that have bought in any of them.
• sort choice
  What to order by: total, count, name, last, sb. Left out, it is total, the dollars awarded.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id bkey agency sub office awards_count awards_total sb_count vendors last_award

Beside the rows: total capped

Example

GET /buyers?naics=332710&sort=count

GET /buyers/{key}

One buying office: what it buys, who wins there, its open notices and the contracts ending there.

Parameters

• key in the address
  The bkey of the office: 32 characters.

The answer holds

id bkey agency sub office awards_count awards_total sb_count vendors last_award top_naics top_vendors by_fy updated_at states set_asides recent recompetes active_opps label behaviour vehicles advocates lead_time yours people_named tracked ot

Some of the time: band entry

Example

GET /buyers/0123456789abcdef0123456789abcdef

GET /agencies

Every agency on record with its offices, awards, open notices and grants counted.

It takes no parameters.

Each row under agencies holds

agency offices subs n s sb last_award slug open_notices grants_n grants_s

Beside the rows: total updated

Example

GET /agencies

GET /agencies/{slug}

One agency: its sub-agencies and offices, what it buys, who wins, and its open notices.

Parameters

• slug in the address
  The slug of the agency, as /agencies returns it.

The answer holds

slug agency awards_count awards_total offices sb_count last_award subs top_offices top_naics top_vendors by_fy open_notices recent_opps recompetes_12 grants grant_programs history_loading updated watched policy

Example

GET /agencies/department-of-defense

Contracting people

GET /contacts

The people named on notices as the point of contact, with the office they buy for.

Parameters

• q text
  Part of a name, a job title or an email address.
• buyer text
  Part of the name of a buying office or sub-agency.
• agency text
  Part of the name of a department or sub-agency.
• naics list
  NAICS codes, separated by commas: people whose notices are most often in any of them.
• open_only switch
  Send 1 for people with a notice open now.
• role choice
  What the person is there for: smallbiz, officer, specialist or technical.
• sort choice
  What to order by: notices, open, name, office, last. Left out, it is notices, the number of notices that name them.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id ckey name title email phone ptype dept subtier office bkey notices open_notices first_seen last_seen top_naics role role_label role_says

Beside the rows: total capped roles answer

Example

GET /contacts?buyer=aviation&open_only=1

GET /contacts/{id}

One contracting person: their open notices, their recent ones and the colleagues in the same office.

Parameters

• id in the address
  The id of the person, or their ckey.

The answer holds

id ckey name title email phone ptype dept subtier office bkey notices open_notices first_seen last_seen top_naics top_psc updated_at notices_open notices_recent colleagues tracked

Example

GET /contacts/5521

Vehicles

GET /vehicles

Contract vehicles on record: who holds each, its ceiling, what has been ordered and when it ends.

Parameters

• q text
  Part of a holder name, a contract number, a description or a solicitation number.
• naics list
  NAICS codes, separated by commas.
• psc list
  Product or service codes, separated by commas.
• kind list
  Kinds of vehicle, separated by commas: gwac, schedule, bpa, boa, idiq, idv.
• set_aside list
  Set-aside codes, separated by commas, as /set-asides lists them.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• holder text
  Part of the name of the company that holds it.
• buyer text
  Part of the name of a buying office or sub-agency.
• agency text
  Part of the name of an agency.
• bkey text
  One buying office, by its bkey.
• entity_id whole number
  The company that holds it, as a company id.
• live switch
  Send 1 for vehicles still inside their ordering period.
• dormant switch
  Send 1 for vehicles whose ordering period has ended.
• multi switch
  Send 1 for vehicles with more than one holder.
• sole switch
  Send 1 for vehicles with one holder.
• ends_within whole number
  Live vehicles that end within this many days.
• headroom whole number
  Vehicles with a ceiling that have used at most this per cent of it.
• min_ceiling number
  A ceiling of at least this many dollars.
• ordering switch
  Send 1 for vehicles with at least one order on record.
• watch_only switch
  Send 1 to keep only what your own watches match.
• sort choice
  What to order by: ends, ceiling, ordered, orders, used, holders, holder, buyer, start, last_order. Left out, it is ends: live vehicles first, the soonest end date at the top.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id vkey award_id gen_id piid solicitation_id kind idv_type holder holder_entity_id holders awarding_agency awarding_sub awarding_office bkey naics psc set_aside_code pop_state ceiling ordered used_pct orders order_codes start_date end_date potential_end_date last_order days_left live description signals updated_at naics_title kind_label own codes_carried carries via ordered_to ordered_to_more

Beside the rows: total capped totals facets

Example

GET /vehicles?naics=541330&live=1&multi=1

GET /vehicles/{id}

One vehicle: its orders, the codes ordered under it, the other holders and the subcontractors named under it.

Parameters

• id in the address
  The id of the vehicle, or its vkey.

The answer holds

id vkey award_id gen_id piid solicitation_id kind idv_type holder holder_entity_id holders awarding_agency awarding_sub awarding_office bkey naics psc set_aside_code pop_state ceiling ordered used_pct orders order_codes start_date end_date potential_end_date last_order days_left live description signals updated_at naics_title kind_label orders_listed orders_list top_codes order_holders orders_recent co_holders band buyer_vehicles subcontractors standing left carries codes_n watching way_in

Some of the time: pipeline

Example

GET /vehicles/774

Subawards and grants

GET /subawards

Subcontracts that prime contractors reported, newest first.

Parameters

• q text
  Words in the description, the subcontractor name or the prime name.
• naics list
  NAICS codes, separated by commas.
• psc list
  Product or service codes, separated by commas.
• state list
  Two-letter state codes, separated by commas: where the subcontractor is, or where the work is performed.
• prime text
  Part of the name of the prime contractor.
• sub text
  Part of the name of the subcontractor.
• agency text
  Part of the name of an agency.
• prime_uei text
  The prime contractor, by its Unique Entity ID.
• prime_gen_id text
  The prime award, by its gen_id.
• from date
  Dated on or after this, as YYYY-MM-DD.
• to date
  Dated on or before this, as YYYY-MM-DD.
• fy whole number
  One federal fiscal year.
• min number
  A subaward of at least this many dollars.
• max number
  A subaward of at most this many dollars.
• sort choice
  What to order by: date, amount, sub, prime, state. Left out, it is date.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id sub_id prime_gen_id prime_piid prime_name prime_uei sub_name sub_uei amount sub_date sub_type description naics naics_desc psc awarding_agency awarding_sub sub_city sub_state sub_zip sub_county pop_city pop_state fy entity_id prime_entity_id

Beside the rows: total capped sum sum_capped facets answer index

Example

GET /subawards?naics=336413&state=FL&min=100000

GET /subawards/{id}

One subaward: the prime award it sits under and the other subawards beside it.

Parameters

• id in the address
  The id of the subaward.

The answer holds

id sub_id src prime_gen_id prime_piid idv_piid prime_value withdrawn prime_name prime_uei prime_entity_id sub_name sub_uei entity_id amount sub_date sub_type description naics naics_desc psc psc_desc awarding_agency awarding_sub sub_city sub_state sub_zip sub_county pop_city pop_state fy created_at updated_at naics_title usaspending_url prime_award siblings sub_other prime_other open_same_code

Some of the time: pipeline

Example

GET /subawards/20418

GET /grants

Grants and other federal assistance awards on record, newest first.

Parameters

• q text
  Words in the description, the recipient name or the program title.
• state list
  Two-letter state codes, separated by commas: where the recipient is, or where the work is performed.
• agency text
  Part of the name of an agency.
• buyer text
  Part of the name of the awarding sub-agency or agency.
• recipient text
  Part of the name of the recipient.
• cfda text
  An assistance listing number, or the start of one.
• gtype text
  One kind of assistance, by its two-digit code. The answer lists the codes under types.
• from date
  Started on or after this date, as YYYY-MM-DD.
• to date
  Started on or before this date, as YYYY-MM-DD.
• fy whole number
  One federal fiscal year.
• min number
  At least this many dollars.
• max number
  At most this many dollars.
• sort choice
  What to order by: date, amount, end, recipient, agency, cfda. Left out, it is date, the start date.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id gen_id fain recipient_name recipient_uei awarding_agency awarding_sub cfda cfda_title award_type type_code description amount outlays start_date end_date pop_city pop_state rec_city rec_state fy

Beside the rows: total capped sum sum_capped facets types

Example

GET /grants?state=FL&fy=2025&sort=amount

GET /grants/{id}

One assistance award, with others under the same program and to the same recipient, and what the recipient reported passing on under it.

Parameters

• id in the address
  The id of the award.

The answer holds

id gen_id fain recipient_name recipient_uei awarding_agency awarding_sub funding_agency cfda cfda_title award_type type_code description amount outlays start_date end_date last_modified pop_city pop_state pop_county pop_country rec_city rec_state rec_zip rec_country fy created_at updated_at type_name usaspending_url sam_listing_url same_program same_recipient passed_on

Example

GET /grants/6602

GET /grant-opps

Funding opportunities that are open or forecast, the soonest closing first.

Parameters

• q text
  Words in the title, the description or the opportunity number.
• agency text
  Part of an agency name, or an agency code.
• aln text
  Part of an assistance listing number.
• status text
  The status the source gives: posted or forecasted.
• active choice
  1 for opportunities still open, 0 for the ones that have closed. Left out, it is 1.
• deadline_from date
  Closing on or after this date.
• deadline_to date
  Closing on or before this date.
• min number
  An award ceiling of at least this many dollars.
• cost_sharing choice
  1 for opportunities that ask for cost sharing, 2 for the ones that do not.
• sort choice
  What to order by: deadline, money, agency, opened, title. Left out, open opportunities come first, the soonest closing date at the top.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id opp_id number title agency agency_code aln opp_status open_date close_date active award_ceiling award_floor total_funding expected_awards cost_sharing

Beside the rows: total capped totals facets

Example

GET /grant-opps?q=manufacturing&sort=deadline&dir=asc

GET /grant-opps/{id}

One funding opportunity, with what was awarded under the same program before.

Parameters

• id in the address
  The id of the opportunity, or its number.

The answer holds

id opp_id number title agency agency_code aln doc_type opp_status open_date close_date active description award_ceiling award_floor total_funding expected_awards cost_sharing applicant_types contact_name contact_email url detail_fetched created_at updated_at url_gov prior related

Some of the time: prior_stats

Example

GET /grant-opps/1187

GET /programs

The programs that grants and other assistance are made under, as SAM.gov lists them, in number order.

Parameters

• q text
  Words in the title or the objective, or a program number or the start of one.
• agency text
  Part of the name of the agency, the department or the office that runs the program.
• status choice
  active for programs still listed as active, inactive for the others. Left out, it is both.
• kind text
  Part of a kind of assistance, as the assist_types field holds it.
• sort choice
  number, or amount for the largest stated obligation first. Left out, it is number, with active programs first.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 100. Left out, it is 50.

Each row under rows holds

number title popular department agency assist_types oblig_fy oblig_amt status active published

Beside the rows: page per_page more total on_file whole need

Example

GET /programs?q=research&status=active

GET /programs/{number}

One program: what its listing says, the grants on record under its number, what was passed on under them and the opportunities open under it.

Parameters

• number in the address
  The program number, such as 12.300.

The answer holds

number listing setting_up whole grants subgrants opps

Some of the time: says

Example

GET /programs/12.300

Forecast

GET /forecast

Buys expected to come round again, worked out from how often each office has bought the same thing. Each row is an estimate.

Parameters

• months whole number
  How many months ahead to look, up to what your plan reaches. Left out, it is 12.
• naics list
  NAICS codes, separated by commas.
• psc list
  Product or service codes, separated by commas.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• buyer text
  Part of the name of a buying office or sub-agency.
• agency text
  Part of the name of an agency.
• set_aside list
  Set-aside codes, separated by commas, as /set-asides lists them. ANY_SB means any small business set-aside.
• min number
  A typical award of at least this many dollars.
• max number
  A typical award of at most this many dollars.
• confidence whole number
  A confidence of at least this, from 1 to 99.
• source choice
  derived for forecasts worked out from past awards, agency for the ones an agency published.
• watch_only switch
  Send 1 to keep only what your own watches match.
• sort choice
  What to order by: next, confidence, amount, buys, buyer. Left out, it is next, the expected date.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id fkey bkey awarding_agency awarding_sub awarding_office naics psc buys span_days median_gap gap_spread last_award next_expected window_start window_end median_amount total_amount last_vendor last_entity_id vendors sb_share set_aside_code pop_state confidence signals source batch title ref contact fy updated_at naics_title

Beside the rows: total capped months source by_source sum facets

Example

GET /forecast?naics=332710&months=18&confidence=60

Price bands

GET /price-bands

What a kind of work has gone for, by code and buying office: the middle award, the range, and how contested it was.

Parameters

• scope choice
  office for one band for each office, national for one band for each code across every office. Left out, it is office.
• naics list
  NAICS codes, separated by commas.
• psc list
  Product or service codes, separated by commas.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• buyer text
  Part of the name of a buying office or sub-agency.
• agency text
  Part of the name of an agency.
• min number
  A middle award of at least this many dollars.
• max number
  A middle award of at most this many dollars.
• thin whole number
  Bands where at least this per cent of awards drew one offer.
• open_field whole number
  Bands where the largest supplier holds at most this per cent.
• watch_only switch
  Send 1 to keep only what your own watches match.
• sort choice
  What to order by: awards, amount, single, held, trend, buyer, last. Left out, it is awards, the number of awards behind the band.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id pkey scope bkey naics psc awarding_agency awarding_sub awarding_office awards sampled total_amount p10 p25 median_amount p75 p90 min_amount max_amount p25_ceiling median_ceiling p75_ceiling ceiling_awards median_days competed_pct sole_pct one_offer_pct median_offers fixed_price_pct sb_share vendors top_vendor top_share trend_pct pop_state first_award last_award signals updated_at naics_title

Some of the time: national

Beside the rows: total capped scope facets

Example

GET /price-bands?naics=332710&scope=national

GET /price-bands/{id}

One price band, with the awards nearest the middle, the largest, the smallest and the most recent.

Parameters

• id in the address
  The id of the band, or its pkey.

The answer holds

id pkey scope bkey naics psc awarding_agency awarding_sub awarding_office awards sampled total_amount p10 p25 median_amount p75 p90 min_amount max_amount p25_ceiling median_ceiling p75_ceiling ceiling_awards median_days competed_pct sole_pct one_offer_pct median_offers fixed_price_pct sb_share vendors top_vendor top_share trend_pct pop_state first_award last_award signals updated_at naics_title typical largest smallest recent top_vendors other_offices labor top_vendors_of

Some of the time: national

Example

GET /price-bands/2290

Ways in

GET /entry

Markets by how often they take on a supplier they have not bought from before, and what a first win there looks like.

Parameters

• scope choice
  office for one row for each office and code, national for one row for each code. Left out, it is office.
• naics list
  NAICS codes, separated by commas.
• buyer text
  Part of the name of a buying office or sub-agency.
• agency text
  Part of the name of an agency.
• open whole number
  An openness of at least this, from 1 to 99.
• door_max number
  A typical first award of at most this many dollars.
• leads_somewhere whole number
  Markets where at least this per cent of new suppliers won again.
• watch_only switch
  Send 1 to keep only what your own watches match.
• sort choice
  What to order by: fit, open, entrants, door, repeat, awards, buyer. Left out, it is fit: the markets that suit your account's codes and state come first.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id ekey scope bkey naics awarding_agency awarding_sub awarding_office awards vendors entrants entry_rate entrant_share door_amount door_setaside_pct door_competed_pct door_one_offer_pct repeat_pct ladder_days ladder_ratio days_since_entry openness signals updated_at naics_title

Some of the time: fit why parts built

Beside the rows: total capped scope ranked facets

Example

GET /entry?naics=332710&open=50

GET /entry/{id}

One market from The way in, with the suppliers that got in most recently.

Parameters

• id in the address
  The id of the market, or its ekey.

The answer holds

id ekey scope bkey naics awarding_agency awarding_sub awarding_office awards vendors entrants entry_rate entrant_share door_amount door_setaside_pct door_competed_pct door_one_offer_pct repeat_pct ladder_days ladder_ratio days_since_entry openness signals updated_at naics_title entrants_list entrants_skipped band other_offices

Some of the time: national history

Example

GET /entry/518

GET /routes

Ways into one code, ranked by how hard each is: bidding direct, through a prime, through a vehicle, or with a partner.

Parameters

• naics text
  One NAICS code to route into. Left out, it is the primary code on your account.
• psc text
  One product or service code, read when there is no NAICS code: send naics empty, and the routes are found through the NAICS codes that product is bought under.
• state text
  One two-letter state, to keep to work performed there.
• bkey text
  One buying office, by its bkey.

Each row under routes holds

kind hops friction reach bkey office agency through headline why typical last_seen signals

Some of the time: openness

Beside the rows: reason home

Example

GET /routes?naics=332710&state=FL

GET /jna

Published justifications for awards made without full competition: who holds the work, under what authority, and when it ends.

Parameters

• q text
  Words in the title, the incumbent name or the solicitation number.
• authority text
  The authority cited, by its code.
• authority_name text
  The authority cited, by its full name as the authority_name field holds it.
• agency text
  Part of the name of a department or sub-agency.
• buyer text
  Part of the name of a buying office or sub-agency.
• naics list
  NAICS codes, separated by commas. A code of fewer than six digits matches every code that starts with it.
• psc list
  Product or service codes, separated by commas.
• state list
  Two-letter state codes, separated by commas: where the work is performed.
• entity_id whole number
  The incumbent, as a company id.
• min number
  A value of at least this many dollars.
• from date
  Posted on or after this date, as YYYY-MM-DD.
• to date
  Posted on or before this date, as YYYY-MM-DD.
• expiring whole number
  Justifications whose period ends within this many months, from 1 to 60.
• sort choice
  What to order by: door, ends, next, amount, incumbent, posted. Left out, it is door: the ones still running come first, the soonest end at the top.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id notice_id opp_id posted title sol_number award_number dept subtier office naics psc pop_state authority authority_name incumbent incumbent_uei entity_id amount period_end next_compete found bkey

Beside the rows: total capped sum summary filtered facets

Example

GET /jna?naics=3364&expiring=12

GET /jna/{id}

One justification: what its authority means, the notice it was published on, and the incumbent's other awards.

Parameters

• id in the address
  The id of the justification.

The answer holds

id notice_id opp_id posted title sol_number award_number dept subtier office naics psc pop_state authority authority_name incumbent incumbent_uei norm_name entity_id amount period_end next_compete actions found ui_link created_at updated_at meaning read notice bkey pattern history

Some of the time: pipeline

Example

GET /jna/342

Rules, bills and clauses

GET /policy

Federal rules and bills in Congress that bear on federal buying. One address, three lists: tab says which.

Parameters

• tab choice
  open for rules still taking comments, rules for every rule, bills for bills in Congress. Left out, it is open.
• q text
  Words in the title or the summary.
• naics list
  NAICS codes, separated by commas: rules or bills tagged with any of them.
• psc list
  Product or service codes, separated by commas: rules or bills tagged with any of them.
• type text
  Rules only. The kind of document, as the doc_type field holds it.
• regulation text
  Rules only. FAR or DFARS.
• acq switch
  Rules only. Send 1 for rules that change how the government buys.
• cfr whole number
  Rules only. One title of the Code of Federal Regulations, by number.
• agency text
  Rules only. Part of the name of an agency.
• from date
  Rules only. Published on or after this date, as YYYY-MM-DD.
• to date
  Rules only. Published on or before this date, as YYYY-MM-DD.
• flag text
  Bills only. One flag, as the flags field holds it.
• stage text
  Bills only. How far the bill has got, as the stage field holds it.
• congress whole number
  Bills only. One Congress, by number.
• fy whole number
  Bills only. The fiscal year a bill funds.
• sort choice
  What to order by: deadline, published, effective, title, action, introduced. Rules take deadline, published, effective and title, and left out it is deadline. Bills take action, introduced and title, and left out it is action.
• dir choice
  asc or desc. Left out, it is desc.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 500, up to what your plan shows on a page. Left out, it is 50.

Each row under rows holds

id fr_doc regs_id docket_id doc_type title published effective comment_start comment_end open comment_url agencies cfr_titles cfr_parts clauses acq_flag regulation acq_why reach significant fr_url regs_url tags

Beside the rows: total capped facets tab

These are the fields of a rule. With tab=bills a row holds: id bkey congress bill_type bill_number title policy_area sponsor introduced action_date action_text stage law_number flags fy congress_url tags.

Example

GET /policy?tab=rules&regulation=DFARS&acq=1

GET /policy/rule/{id}

One rule, with the codes and agencies it bears on and the open notices that cite its clauses.

Parameters

• id in the address
  The id of the rule.

The answer holds

id rkey fr_doc regs_id docket_id source doc_type title abstract action published effective comment_start comment_end open comment_url agencies agency_slugs agency_code cfr_titles cfr_parts clauses acq_flag regulation acq_why reach docket_ids rin topics significant fr_url regs_url tagged modified created_at updated_at tags market cfr_meaning notices

Example

GET /policy/rule/915

GET /policy/bill/{id}

One bill, with the codes it bears on and the budget lines of the year it funds.

Parameters

• id in the address
  The id of the bill.

The answer holds

id bkey congress bill_type bill_number title policy_area subjects summary sponsor origin introduced action_date action_text stage law_number flags fy congress_url api_url detail_fetched tagged updated created_at updated_at tags market budget stages

Example

GET /policy/bill/208

GET /clauses

FAR and DFARS clauses, by number or by words in them.

Parameters

• q text
  A clause number or the start of one, or words in the title or the text.
• reg choice
  FAR or DFARS.
• flag text
  One family of clauses, by the start of its number, as the answer lists them under families.
• limit whole number
  How many clauses to return, from 1 to 100. Left out, it is 40.

Each row under rows holds

id number reg part title chars prescribed_by is_clause amended_on weight href minutes

Some of the time: source_url

Beside the rows: q reg flag stats families

Example

GET /clauses?q=252.204&reg=DFARS

GET /clauses/{number}

One clause in full, with the rules that would change it and the open notices that cite it.

Parameters

• number in the address
  The clause number, such as 52.219-14.

The answer holds

clause related

Example

GET /clauses/52.219-14

Codes

GET /naics

Every NAICS code with awards on record, with the awards and dollars counted for each.

It takes no parameters.

Each row under by_naics holds

c n s title

Beside the rows: coverage

Example

GET /naics

GET /naics/{code}

One code: awards by year, the offices that buy it, the companies that win it, open notices and contracts ending.

Parameters

• code in the address
  A six-digit NAICS code.

The answer holds

code title awards total avg vendors fy_first fy_last median by_fy top_buyers top_subs top_vendors set_asides states psc bands competition offers_avg recent_awards awards_built active_opps opps_90d recompetes_12 recompetes_12_sum recent_opps upcoming updated summary watched size policy budget

Example

GET /naics/332710

GET /data/naics/{code}

The same code as a short answer whose shape is named and does not change: made for a spreadsheet or a script.

Parameters

• code in the address
  A six-digit NAICS code.

The answer holds

schema code title as_of awards by_fiscal_year top_buyers top_vendors set_asides open_notices recompetes_12

Some of the time: last_week

Example

GET /data/naics/332710

GET /psc

Every product or service code with awards on record, with the awards and dollars counted for each.

It takes no parameters.

Each row under codes holds

c d n s

Beside the rows: total updated

Example

GET /psc

GET /psc/{code}

One product or service code: awards by year, who buys it, who wins it, open notices and contracts ending.

Parameters

• code in the address
  A product or service code, up to four characters.

The answer holds

code title awards total avg vendors fy_first fy_last median by_fy top_buyers top_vendors top_naics set_asides states bands competition active_opps recompetes_12 recompetes_12_sum upcoming recent_opps recent_awards updated watched

Some of the time: ref

Example

GET /psc/4820

GET /set-asides

Every set-aside code on record with its name, and the awards and dollars made under it.

It takes no parameters.

Each row under codes holds

k n s title

Beside the rows: updated names

Example

GET /set-asides

GET /set-asides/{code}

One set-aside: awards by year, the codes it is used in, who buys under it and who wins.

Parameters

• code in the address
  A set-aside code, as /set-asides lists them.

The answer holds

code title awards total avg vendors fy_first fy_last by_fy top_naics top_buyers top_vendors states bands active_opps recompetes_12 upcoming updated

Example

GET /set-asides/SBA

Per diem rates

GET /perdiem

GSA per diem rates for one fiscal year: the places in a state, or the places that match a name, each with lodging by month and meals.

Parameters

• state text
  One two-letter state code: the places GSA lists in it.
• q text
  Part of the name of a city or a county.
• fy whole number
  One federal fiscal year on file. Left out, it is the current one.

Each row under rows holds

fy std state city county did m lo hi meals fl

Beside the rows: on_file years fy last_fy state q other more std tiers

Example

GET /perdiem?state=VA&q=fairfax

GET /perdiem/place

One place GSA gives a rate for, with its lodging and meals for every fiscal year on file.

Parameters

• state text
  The two-letter state code of the place.
• city text
  The name of the place, as the city field of /perdiem holds it.
• did whole number
  The number GSA gives the place, as the did field of /perdiem holds it. It tells two places of one name apart.
• std switch
  Send 1 for the standard rate of the state, which applies where GSA lists no place.

The answer holds

on_file place years

Some of the time: last_fy says

Example

GET /perdiem/place?state=VA&city=Fairfax

Court and lobbying

GET /court

Decisions of the Court of Federal Claims, the newest first: bid protests and contract cases, each with its party, its judge and the document.

Parameters

• q text
  Words in the title of the case, each of three letters or more.
• year whole number
  Decisions dated in one calendar year.
• protest switch
  Send 1 for bid protests only.
• entity whole number
  The company a case is tied to, as a company id.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 100. Left out, it is 50.

Each row under rows holds

id granule package case_no title opinion party entity_id decided nos_code nos is_protest protest_why judge pdf_url txt_url details_url entity_name

Beside the rows: page per_page more on_file whole reading slow failed need capped company

Example

GET /court?protest=1&year=2025

GET /court/entity/{id}

What one company has at the Court of Federal Claims: its cases counted, how many are bid protests, and its latest decisions.

Parameters

• id in the address
  The id of the company, as /entities returns it.

Each row under rows holds

id granule package case_no title opinion party entity_id decided nos_code nos is_protest protest_why judge pdf_url txt_url details_url

Beside the rows: on_file cases protests opinions more

Example

GET /court/entity/3310

GET /lobbying

Filings made under the Lobbying Disclosure Act, the newest posted first: who the client is, which firm filed, for which period and what was reported.

Parameters

• q text
  Words in the name of the client or of the firm that filed, each of three letters or more.
• year whole number
  Filings for one calendar year.
• issue text
  One issue area, by its three-letter code. The answer lists the codes under issues.
• body whole number
  One part of the government that was contacted, by its number. The answer lists the numbers under bodies.
• entity whole number
  The company a filing is tied to, as a company id.
• page whole number
  Which page, counted from 1.
• per_page whole number
  Rows on a page, from 1 to 100. Left out, it is 50.

Each row under rows holds

id ftype ftype_name fyear fperiod fperiod_name amend reg_name client_name client_desc client_state self income expenses posted doc_url entity_id tie tie_on period as_of issues

Beside the rows: page per_page more on_file whole by slow failed need capped reading

Example

GET /lobbying?issue=DEF&year=2025

GET /lobbying/{id}

One filing, with each issue lobbied on, what was said about it and the parts of the government that were contacted.

Parameters

• id in the address
  The id of the filing.

The answer holds

id ftype ftype_name fyear fperiod fperiod_name amend reg_name client_name client_desc client_state self income expenses posted doc_url entity_id tie tie_on period as_of acts tie_words company vouch

Example

GET /lobbying/20418

GET /lobbying/company/{id}

What one company has on file: by year what it reported spending and what the firms it hired reported being paid, the issues, and its newest filings.

Parameters

• id in the address
  The id of the company, as /entities returns it.

The answer holds

on_file any whole reading entity_id

Some of the time: capped years firms firms_n filings issues issues_n bodies bodies_n latest ties as_of vouch

A company with no filing tied to it answers the first five alone. The rest are there when any is true.

Example

GET /lobbying/company/3310

GET /lobbying/agency/{slug}

Who reported contacting one agency, year by year, counted from the filings on file.

Parameters

• slug in the address
  The slug of the agency, as /agencies returns it.

The answer holds

matched any

Some of the time: bodies body pending years as_of vouch

An agency that no part of the government named on a filing stands for answers matched and any alone.

Example

GET /lobbying/agency/department-of-defense

Your own work

GET /saved

The views you saved, and the ones your account shares: each is a list and the filters it was saved with.

It takes no parameters.

Each row holds

id user_id name kind filters sort dir alert pinned shared opened last_opened last_alert export_freq last_export created_at mine can_export

Some of the time: author

Example

GET /saved

GET /watches

What you are watching: codes, offices, companies, states, keywords and single notices.

Parameters

• pulse switch
  Send 1 to get the list under watches, with what is new for each under pulse.

Each row holds

id kind value label created_at

Example

GET /watches

GET /pipeline

Your account's pursuits, read only: each with its stage, owner, value and next step.

Parameters

• owner text
  me for your own, none for pursuits nobody owns, or the id of one person on the account.
• stage text
  One stage, by its key. The answer lists the keys under stages.

Each row under items holds

id user_id kind ref_id stage title buyer naics amount due notes outcome_reason outcome_note bid_price won_price settled_at by_id owner_id next_step next_due est_value pwin rfp_on award_on role bid_id contract_id scorecard created_at updated_at by owner next_overdue stage_label open days_left href role_label value value_from weighted pursuit_href capture_href bid_href matrix_href contract_href bid contract matrix tasks

Beside the rows: counts stages summary forecast

Example

GET /pipeline?stage=pursuing

GET /pipeline/{id}

One pursuit on your pipeline, with its tasks, gates and reviews.

Parameters

• id in the address
  The id of the pursuit.

The answer holds

item tasks gates reviews gate gate_labels review_gates colours decisions stages roles reasons people shared me

Example

GET /pipeline/12

Exports

GET /export/{kind}

One list as a CSV or Excel file, with the same filters the list takes. Each row counts toward the export rows of your month.

Parameters

• kind in the address
  Which list. The kinds are named under Export kinds.
• fmt choice
  csv or xlsx. Left out, it is csv.
• json switch
  Send 1 to get the file inside a JSON answer: rows, csv and filename.

Beside these, send the filters of the list being exported, exactly as that list takes them.

The answer holds

rows csv filename

These are the fields of the answer when json=1. Otherwise the answer is the file itself.

Example

GET /export/awards?naics=332710&fy=2025&fmt=xlsx