USAspending API ReferenceIndependent
Try the API

Custom Account Data

POST/api/v2/download/accounts/
Powers Custom award and account data on usaspending.gov How the Download Center works

These endpoints are used to power USAspending.gov's download center.

Generate files and return metadata using filters on custom account

Request

curl -X POST 'https://api.usaspending.gov/api/v2/download/accounts/' \
  -H 'Content-Type: application/json' \
  -d '{
  "account_level": "treasury_account",
  "file_format": "csv",
  "filters": {
    "fy": "2018",
    "quarter": "1",
    "submission_types": [
      "account_balances",
      "award_financial"
    ],
    "def_codes": [
      "L",
      "M",
      "O"
    ]
  }
}'

Request body

The filters object is shared by every search endpoint. The filter object explains each filter with examples.

  • account_levelenum (string)Required

    The account level is used to filter for a specific type of file.

    Allowed values
    • federal_account
    • treasury_account
  • file_formatenum (string)

    The format of the file(s) in the zip file containing the data.

    Allowed values
    • csv
    • tsv
    • pstxt

    Default csv

  • filtersobject · AdvancedFilterObjectRequired10 fields

    The filters used to filter the data

    • agencystring

      The agency on which to filter. This field expects either an internal toptier agency identifier, also known as the toptier_agency_id, or an agency abbreviation (DOJ, NRC, etc.). If the string submitted contains only numbers, it will search for a matching toptier_agency_id. Otherwise, it will search for a matching abbreviation.

      Default all

    • budget_functionstring

      The budget function code on which to filter.

    • budget_subfunctionstring

      The budget subfunction code on whicn to filter

    • federal_accountstring

      This field is an internal id.

    • submission_typeenum (string)

      Either submission_type or submission_types is required.

      Allowed values
      • account_balances
      • object_class_program_activity
      • award_financial
    • submission_typesarray

      Either submission_type or submission_types is required.

      • (enum[string])
        • account_balances
        • object_class_program_activity
        • award_financial
    • fystringRequired

      The fiscal year to filter by in the format YYYY

    • quarterenum (string)

      Either quarter or period is required. Do not supply both. Note that both monthly and quarterly submissions will be included in the resulting download file even if only quarter is provided.

      Allowed values
      • 1
      • 2
      • 3
      • 4
    • periodenum (string)

      Either quarter or period is required. Do not supply both. Agencies cannot submit data for period 1 so it is disallowed as a query filter. Note that both monthly and quarterly submissions will be included in the resulting download file even if only period is provided.

      Allowed values
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
    • def_codesarray of string

      The Disaster Emergency Fund Code (def_codes) filter is optional. If no def_codes are provided the request will return records associated with all def_codes. If an array of valid members is provided the request will return records associated with only the def_codes provided.

      • A list of current DEFC can be found here.
  • columnsarray of string

    The columns specified to be included in the download.

    Default all columns

Try it

Runs against the live API. Responses are real data.

POST/api/v2/download/accounts/

Response · 200

  • status_urlstringRequired

    The endpoint used to get the status of a download.

  • file_namestringRequired

    Is the name of the zipfile containing CSVs that will be generated (file_name is timestamp followed by _transactions or _awards).

  • file_urlstringRequired

    The URL for the file.

  • download_requestobjectRequired

    The JSON object used when processing the download.

Example response
{
  "status_url": "http://localhost:8000/api/v2/download/status?file_name=FY2018Q1_All_TAS_AccountBalances_2020-01-13_H21M00S18407575.zip",
  "file_name": "FY2018Q1_All_TAS_AccountData_2020-01-13_H21M00S18407575.zip",
  "file_url": "/csv_downloads/FY2018Q1_All_TAS_AccountData_2020-01-13_H21M00S18407575.zip",
  "download_request": {
    "account_level": "treasury_account",
    "agency": "all",
    "columns": [],
    "download_types": [
      "account_balances",
      "award_financial"
    ],
    "file_format": "csv",
    "filters": {
      "fy": 2018,
      "quarter": 1,
      "def_codes": [
        "L",
        "M",
        "O"
      ]
    },
    "request_type": "account"
  }
}

Recent changes

Generated from contracts/v2/download/accounts.md in the USAspending API repo.

Loading…