Filing Your Taxes Online is Fast, Easy and Secure.
Start now and receive your tax refund in as little as 7 days.

1. Get Answers

Your online questions are customized to your unique tax situation.

2. Maximize your Refund

Find tax credits for everything from school tuition to buying a hybri

3. E-File for FREE

E-file free with direct deposit to get your refund in as few as 7 days.

Filing your taxes with paper mail can be difficult and it could take weeks for your refund to arrive. IRS e-file is easy, fast and secure. There is no paperwork going to the IRS so tax refunds can be processed in as little as 7 days with direct deposit. As you prepare your taxes online, you can see your tax refund in real time.

FREE audit support and representation from an enrolled agent – NEW and only from H&R Block

Tax Filing

Cheapest State Tax Return1040x For 2009Amend Income Tax ReturnOnline State Tax FilingAmended Federal Tax ReturnFree File 2012 Taxes OnlineH And R Block Free FileFile 1040ez ElectronicallyH And R Block Free Tax ReturnCheap State Taxes OnlineState Ms Income Tax Form 20052010 Tax Form 1040Free 1040ez 2014Form 1040nr Instructions1040ez Instructions 2013Visit Www Irs Gov Freefile2011 Tax PreparationBack Taxes Owed1040es FormForm 1040Turbotax 2012Filing Amended Federal Tax ReturnWww Irs Gov Form1040x1040x 20112012 990 Tax Forms2011 Tax Forms 1040ezHrblock 1040xMypay Dfas Mil2010 1040 Tax FormsIrs Forms 1040Tax Amendment Form 1040xFree 1040ezFile 2009 Taxes Online For Free2010 Tax Form 1040How Do I File Taxes As A Student2011 Income TaxFree 2011 Taxes Online2010 Federal Tax Form1040ez 2011 PdfIrs Gov Form 1040

Tax Filing

Tax filing Index A Accelerated Cost Recovery System (ACRS), MACRS Depreciation (see also Modified Accelerated Cost Recovery System (MACRS)) Effective date, Depreciation Methods Accounting methods Accrual method, Accrual method. Tax filing Cash method, Cash method. Tax filing Change of method, Changing your accounting method. Tax filing Constructive receipt of income, Cash method. Tax filing , More information. Tax filing Accrual method taxpayers, Accrual method. Tax filing ACRS (Accelerated Cost Recovery System) Effective date, Depreciation Methods Active participation, Active participation. Tax filing Activities not for profit, Duplex. Tax filing Additions to property, Additions or improvements to property. Tax filing (see also Improvements) Basis, Increases to basis. Tax filing , Additions or improvements. Tax filing MACRS recovery period, Additions or improvements to property. Tax filing Adjusted basis MACRS depreciation, Adjusted Basis Adjusted gross income (AGI) Modified (see Modified adjusted gross income (MAGI)) Advance rent, Advance rent. Tax filing Security deposits, Security deposits. Tax filing Advertising, Types of Expenses Allocation of expenses Change of property to rental use, Payments added to capital account. Tax filing How to divide expenses, Dividing Expenses Part of property rented, Renting Part of Property, How to divide expenses. Tax filing Personal use of rental property, Personal use of rental property. Tax filing , Personal Use of Dwelling Unit (Including Vacation Home) Alternative Depreciation System (ADS) Election of, Electing ADS MACRS, MACRS Depreciation, Table 2-2d. Tax filing Alternative minimum tax (AMT) Accelerated depreciation methods, Alternative minimum tax (AMT). Tax filing Amended returns, Filing an amended return. Tax filing Apartments Basement apartments, Examples. Tax filing Dwelling units, Dwelling unit. Tax filing Appraisal fees, Settlement fees and other costs. Tax filing Assessments for maintenance, Assessments for local improvements. Tax filing Assessments, local (see Local assessments) Assistance (see Tax help) Assumption of mortgage, Assumption of a mortgage. Tax filing Attorneys' fees, Settlement fees and other costs. Tax filing , Increases to basis. Tax filing Automobiles MACRS recovery periods, Property Classes Under GDS B Basis Adjusted basis, Adjusted Basis Assessments for local improvements, Assessments for local improvements. Tax filing Basis other than cost, Basis Other Than Cost Cost basis, Cost Basis Decreases to, Decreases to basis. Tax filing Deductions Capitalization of costs vs. Tax filing , Deducting vs. Tax filing capitalizing costs. Tax filing Not greater than basis, Cost or Other Basis Fully Recovered Fair market value, Fair market value. Tax filing Increases to, Increases to basis. Tax filing MACRS depreciable basis, Basis of Depreciable Property Property changed to rental use, Basis of Property Changed to Rental Use C Capital expenditures Deductions vs. Tax filing effect on basis, Deducting vs. Tax filing capitalizing costs. Tax filing Local benefit taxes, Local benefit taxes. Tax filing Mortgages, payments to obtain, Expenses paid to obtain a mortgage. Tax filing Cars MACRS recovery periods, Property Classes Under GDS Cash method taxpayers, Cash method. Tax filing Casualty losses, Exception for Rental Real Estate With Active Participation Change of accounting method, Changing your accounting method. Tax filing Charitable contributions Use of property, Donation of use of the property. Tax filing Cleaning and maintenance, Types of Expenses Closing costs, Settlement fees and other costs. Tax filing Commissions, Types of Expenses Computers MACRS recovery periods, Property Classes Under GDS Condominiums, Condominiums, Dwelling unit. Tax filing Constructive receipt of income, Cash method. Tax filing , More information. Tax filing Cooperative housing, Cooperative apartments. Tax filing , Cooperatives, Dwelling unit. Tax filing Cost basis, Cost Basis Credit reports, Settlement fees and other costs. Tax filing Credits Residential energy credits, Decreases to basis. Tax filing D Days of personal use, What is a day of personal use? Days used for repairs and maintenance, Days used for repairs and maintenance. Tax filing Deductions Capitalizing costs vs. Tax filing effect on basis, Deducting vs. Tax filing capitalizing costs. Tax filing Depreciation (see Depreciation) Limitations on, Form 4562. Tax filing Passive activity losses (see Passive activity) Depreciation, Depreciation of Rental Property, Changing your accounting method. Tax filing Alternative Depreciation System (ADS) (see Modified Accelerated Cost Recovery System (MACRS)) Basis (see Basis) Change of accounting method, Changing your accounting method. Tax filing Change of property to rental use, Property Changed to Rental Use Claiming correct amount of, Claiming the Correct Amount of Depreciation Declining balance method, Depreciation Methods Duration of property expected to last more than one year, What Rental Property Can Be Depreciated? Eligible property, What Rental Property Can Be Depreciated? First-year expensing, Section 179 deduction. Tax filing MACRS (see Modified Accelerated Cost Recovery System (MACRS)) Methods, Depreciation Methods, Figuring Your Depreciation Deduction Ownership of property, What Rental Property Can Be Depreciated?, Property you own. Tax filing Rental expense, Depreciation. Tax filing Rented property, Rented property. Tax filing Section 179 deduction, Section 179 deduction. Tax filing Special depreciation allowances, Claiming the Special Depreciation Allowance Straight line method, Depreciation Methods Useful life, What Rental Property Can Be Depreciated?, Property having a determinable useful life. Tax filing Vacant rental property, Vacant rental property. Tax filing Discount, bonds and notes issued at (see Original issue discount (OID)) Dividing of expenses (see Allocation of expenses) Dwelling units Definition, Dwelling unit. Tax filing Fair rental price, Fair rental price. Tax filing Personal use of, Personal Use of Dwelling Unit (Including Vacation Home), What is a day of personal use? E Easements, Decreases to basis. Tax filing Equipment rental expense, Rental of equipment. Tax filing F Fair market value (FMV), Fair market value. Tax filing Fair rental price, Dividing Expenses, Fair rental price. Tax filing Fees Loan origination fees, Points, Settlement fees and other costs. Tax filing Points (see Points) Settlement fees and other costs, Settlement fees and other costs. Tax filing Tax return preparation fees, Legal and other professional fees. Tax filing First-year expensing, Section 179 deduction. Tax filing Form 1040 Not rented for profit income, Where to report. Tax filing Part of property rented, Renting Part of Property Rental income and expenses, Reporting Rental Income, Expenses, and Losses Schedule E, Schedule E (Form 1040) Form 1098 Mortgage interest, Form 1098, Mortgage Interest Statement. Tax filing Form 4684 Casualties and thefts, How to report. Tax filing Form 4797 Sales of business property, How to report. Tax filing Form 8582 Passive activity losses, Form 8582. Tax filing , Form 8582 not required. Tax filing Free tax services, Free help with your tax return. Tax filing G Gains and losses At-risk rules, At-Risk Rules Casualty and theft losses, Exception for Rental Real Estate With Active Participation Limits on rental losses, Form 4562. Tax filing Passive activity losses, Passive Activity Limits Rental real estate activities, Exception for Rental Real Estate With Active Participation Sale of rental property, Sale or exchange of rental property. Tax filing , How to report. Tax filing General depreciation system (GDS) (see Modified Accelerated Cost Recovery System (MACRS)) H Help (see Tax help) Home Main home, Main home. Tax filing Use as rental property (see Use of home) I Improvements, Table 1-1. Tax filing Examples of Improvements (see also Repairs) Assessments for local improvements, Assessments for local improvements. Tax filing Basis, Increases to basis. Tax filing , Additions or improvements. Tax filing Depreciation of rented property, Rented property. Tax filing MACRS recovery period, Additions or improvements to property. Tax filing Insurance, Types of Expenses Casualty or theft loss payments, Decreases to basis. Tax filing Change of property to rental use, Property Changed to Rental Use Fire insurance premiums, cost basis, Settlement fees and other costs. Tax filing Part of property rented, Renting Part of Property Premiums paid in advance, Insurance premiums paid in advance. Tax filing Title insurance, cost basis, Settlement fees and other costs. Tax filing Interest payments, Interest expense. Tax filing (see also Mortgages) Loan origination fees, Points Rental expenses, Types of Expenses L Land Cost basis, Separating cost of land and buildings. Tax filing Depreciation, Land. Tax filing Leases Cancellation payments, Canceling a lease. Tax filing Equipment leasing, Rental of equipment. Tax filing Limits Passive activity losses and credits, Passive Activity Limits Rental losses, Limits on Rental Losses Loans Assumption fees, Settlement fees and other costs. Tax filing Charges connected with getting or refinancing, cost basis, Settlement fees and other costs. Tax filing Low or no interest, Loans with low or no interest. Tax filing Origination fees, Points Local assessments, Assessments for local improvements. Tax filing Losses (see Gains and losses) M Missing children, photographs of, Reminders Modified Accelerated Cost Recovery System (MACRS), MACRS Depreciation, Figuring MACRS Depreciation Under ADS Additions or improvements to property, Additions or improvements to property. Tax filing Adjusted basis, Adjusted Basis Alternative Depreciation System (ADS), MACRS Depreciation, Figuring MACRS Depreciation Under ADS Basis other than cost, Basis Other Than Cost Conventions, Conventions Cost basis, Cost Basis Depreciable basis, Basis of Depreciable Property Effective date, Depreciation Methods Excluded property, Excluded Property General Depreciation System (GDS), MACRS Depreciation, Property Classes Under GDS, Figuring Your Depreciation Deduction Nonresidential rental property, Property Classes Under GDS Property used in rental activities (Table 2-1), Table 2-1. Tax filing MACRS Recovery Periods for Property Used in Rental Activities Recovery periods, Table 2-1. Tax filing MACRS Recovery Periods for Property Used in Rental Activities, 5-, 7-, or 15-year property. Tax filing Residential rental property, Property Classes Under GDS, Residential rental property. Tax filing Special depreciation allowances, Claiming the Special Depreciation Allowance Modified adjusted gross income (MAGI), Modified adjusted gross income (MAGI). Tax filing Mortgages, Expenses paid to obtain a mortgage. Tax filing Assumption of, cost basis, Assumption of a mortgage. Tax filing Change of property to rental use, Property Changed to Rental Use End of, OID, Loan or mortgage ends. Tax filing Interest, Interest expense. Tax filing , Property Changed to Rental Use, Renting Part of Property Mortgage insurance premiums, Settlement fees and other costs. Tax filing Part of property rented, Renting Part of Property N Nonresidential real property, Property Classes Under GDS Not-for-profit activities, Duplex. Tax filing O Original issue discount (OID), Points, Loan or mortgage ends. Tax filing P Part interest Expenses, Part interest. Tax filing Income, Part interest. Tax filing Passive activity Maximum special allowance, Maximum special allowance. Tax filing Personal property Rental income from, Property or services. Tax filing Personal use of rental property, Payments added to capital account. Tax filing , Personal Use of Dwelling Unit (Including Vacation Home) (see also Property changed to rental use) Placed-in-service date, Placed in Service Points, Types of Expenses, Points, Settlement fees and other costs. Tax filing Pre-rental expenses, Pre-rental expenses. Tax filing Principal residence (see Home) Profit, property not rented for, Duplex. Tax filing Property changed to rental use, Payments added to capital account. Tax filing Basis, Basis of Property Changed to Rental Use Publications (see Tax help) R Real estate professionals, Real estate professionals. Tax filing Real estate taxes, Real estate taxes. Tax filing Real property trades or businesses, Real property trades or businesses. Tax filing Recordkeeping requirements Travel and transportation expenses, Local transportation expenses. Tax filing , Travel expenses. Tax filing Recovery periods, Property Classes Under GDS Rent, Settlement fees and other costs. Tax filing Advance rent, Advance rent. Tax filing Fair price, Fair rental price. Tax filing Rental expenses, Rental Expenses Advertising, Types of Expenses Allocation between rental and personal uses, Dividing Expenses Change of property to rental use, Property Changed to Rental Use Cleaning and maintenance, Types of Expenses Commissions, Types of Expenses Depreciation, Depreciation. Tax filing Dwelling unit used as home, Dwelling Unit Used as a Home Equipment rental, Rental of equipment. Tax filing Home, property also used as, Rental of property also used as your home. Tax filing Improvements, Table 1-1. Tax filing Examples of Improvements Insurance, Types of Expenses, Insurance premiums paid in advance. Tax filing Interest payments, Types of Expenses, Interest expense. Tax filing Local transportation expenses, Types of Expenses, Local transportation expenses. Tax filing Part of property rented, Renting Part of Property Points, Types of Expenses, Points Pre-rental expenses, Pre-rental expenses. Tax filing Rental payments, Types of Expenses Repairs, Types of Expenses, Repairs and Improvements Sale of property, Vacant while listed for sale. Tax filing Tax return preparation fees, Legal and other professional fees. Tax filing Taxes, Types of Expenses Tenant, paid by, Expenses paid by tenant. Tax filing Travel expenses, Types of Expenses Utilities, Types of Expenses Vacant rental property, Vacant rental property. Tax filing Rental income Advance rent, Advance rent. Tax filing Cancellation of lease payments, Canceling a lease. Tax filing Dwelling unit used as home, Dwelling Unit Used as a Home Lease with option to buy, Lease with option to buy. Tax filing Not rented for profit, Not Rented for Profit Part interest, Part interest. Tax filing Property received from tenant, Property or services. Tax filing Reporting, Accrual method. Tax filing , Which Forms To Use Security deposit, Security deposits. Tax filing Services received from tenant, Property or services. Tax filing Uncollected rent, Uncollected rent. Tax filing Used as home, Rental of property also used as your home. Tax filing Rental losses, Exception for Rental Real Estate With Active Participation (see also Gains and losses) (see also Passive activity) Repairs, Types of Expenses, Repairs and Improvements (see also Improvements) Assessments for maintenance, Assessments for local improvements. Tax filing Personal use of rental property exception for days used for repairs and maintenance, Days used for repairs and maintenance. Tax filing S Sale of property Expenses, Vacant while listed for sale. Tax filing Gain or loss, Sale or exchange of rental property. Tax filing , How to report. Tax filing Main home, Sale of main home used as rental property. Tax filing Section 179 deductions, Section 179 deduction. Tax filing Security deposits, Security deposits. Tax filing Settlement fees, Settlement fees and other costs. Tax filing Shared equity financing agreements, Shared equity financing agreement. Tax filing Special depreciation allowances, Claiming the Special Depreciation Allowance Spouse Material participation, Participating spouse. Tax filing Standard mileage rates, Local transportation expenses. Tax filing Surveys, Settlement fees and other costs. Tax filing T Tables and figures Improvements, examples of (Table 1-1), Table 1-1. Tax filing Examples of Improvements MACRS optional tables (Table 2-2d), Table 2-2d. Tax filing MACRS optional tables (Tables 2-2a, 2-2b, and 2-2c), Tables 2-2a, 2-2b, and 2-2c. Tax filing MACRS recovery periods for property used in rental activities (Table 2-1), Table 2-1. Tax filing MACRS Recovery Periods for Property Used in Rental Activities Tax credits Residential energy credits, effect on basis, Decreases to basis. Tax filing Tax help, How To Get Tax Help Tax return preparation fees, Legal and other professional fees. Tax filing Taxes Deduction of, Types of Expenses Local benefit taxes, Local benefit taxes. Tax filing Real estate taxes, Real estate taxes. Tax filing Transfer taxes, Settlement fees and other costs. Tax filing Theft losses, Theft. Tax filing Title insurance, Settlement fees and other costs. Tax filing Transfer taxes, Settlement fees and other costs. Tax filing Travel and transportation expenses Local transportation expenses, Types of Expenses, Local transportation expenses. Tax filing Recordkeeping, Travel expenses. Tax filing Rental expenses, Types of Expenses Standard mileage rate, Local transportation expenses. Tax filing U Uncollected rent Income, Uncollected rent. Tax filing Use of home Before or after renting, Days used as a main home before or after renting. Tax filing Change to rental use, Property Changed to Rental Use Days of personal use, What is a day of personal use? Fair rental price, Fair rental price. Tax filing Passive activity rules exception, Exception for Personal Use of Dwelling Unit Personal use as dwelling unit, Personal Use of Dwelling Unit (Including Vacation Home) Utilities, Types of Expenses, Increases to basis. Tax filing V Vacant rental property, Vacant rental property. Tax filing Vacation homes Dwelling unit, Dwelling unit. Tax filing Fair rental price, Fair rental price. Tax filing Personal use of, Personal Use of Dwelling Unit (Including Vacation Home) Valuation Fair market value, Fair market value. Tax filing Prev  Up     Home   More Online Publications
Español

About the API

We make the content you see in our directory of federal agencies available in both English and Spanish via a REST API. The API programmatically returns all of the information contained in the directory, or you can query the API to return just a subset of the available information.

If you are using the Federal Agency Directory API and have feedback or want to tell us about your product, please e-mail us.

Changes to the API

On December 28, 2012, we launched version 2.0 of the API and made the following changes:

  • Launched new methods to return directory records in a hierarchical fashion.
  • Results can now be returned using XML and JSONP, as well as straight JSON.
  • The Interface method was removed.

About the Data

The data in the Federal Agency Directory API is based on the English and Spanish federal agency directories. We gather this data from the agency information listed in the U.S. Government Manual, and independent research by our staff.

There is no schedule for data updates; we update data continually, and as needed. Early versions of the API may have incomplete and inconsistent data. We are working to continually develop the data in our directory records.

If you have suggestions about what types of data you would like to see in the Federal Agency Directory API, please e-mail us.

About the Spanish Data

GobiernoUSA.gov and the North American Academy of the Spanish Language (ANLE, per its Spanish acronym) worked together to review federal agencies Spanish translations to ensure language accuracy and consistency throughout the government. ANLE, the highest authority on Spanish language in the United States, and GobiernoUSA.gov have the joined mission of improving and standardizing the use of Spanish language in government communications.

This collaboration, possible through a signed agreement between the two institutions, resulted in a list of official Spanish language translations of federal agencies, available through this API.

Back to Top

Accessing the API

Our Federal Agency Directory API is accessible via HTTP GET requests and does not require a login or API key to use.

The base URL for the API is http://www.usa.gov/api/USAGovAPI/contacts.{format}/. Append the API call you’d like to make to this URL.

Currently, three output formats are available:

  1. JSON (such as http://www.usa.gov/api/USAGovAPI/contacts.json/contacts)
  2. XML (such as http://www.usa.gov/api/USAGovAPI/contacts.xml/contacts)
  3. JSONP (such as http://www.usa.gov/api/USAGovAPI/contacts.jsonp/contacts?callback=callmemaybe). When requesting JSONP, you should include a callback parameter with the name of the callback function you would like called.

For the purposes of this documentation, only JSON sample calls and results will be shown.

API Result Formats

The Federal Agency Directory API returns results in json, with an optional callback parameter to enable jsonp support.

Interactive Documentation for the API

If you're interested in trying out the Federal Agency Directory API, we have an interactive test page. On this page, you can try different parameters and see the results.

Back to Top

API Data Model

The following fields are associated with directory records. Please note that not every record has data in every field, and the API will only return completed fields.

  • Id - A unique identifier for each directory record
  • Name – The name of the agency.
  • Description – A brief description of the agency.
  • Language – Whether the record is in English or Spanish.
  • Subdivision – Used for mailing items to the agency.
  • Street1 – A first line of address information (such as the street address) for the agency’s main office.
  • Street2 – A second line of address information for the agency’s main office.
  • City – The city of the agency’s main office.
  • StateTer – The state of the agency’s main office.
  • Zip – The postal zip code of the agency’s main office.
  • Email – The e-mail address for the agency’s main office.
  • Phone – The phone number of the agency’s main office (may contain more than one).
  • TTY – The TTY number of the agency’s main office (may contain more than one).
  • Tollfree – The toll-free number to contact the agency (may contain more than one).
  • SMS – Any services offered via text messaging by the agency.
  • Synonym – Alternative names used commonly to refer to the agency (may contain more than one).
  • URI – The URL to access the agency’s complete directory record via the API.
  • Source_Url – The USA.gov or GobiernoUSA.gov URL that contains the record.

Back to Top

URLs

The directory API returns several types of URLs that can be used to link to the agency.

  • Web_Url – Main URLs for the agency (may contain more than one).
  • Contact_Url – URLs for the public to contact the agency (may contain more than one).
  • In_Person_Url – URLs for the public to find out how to interact with the agney in person (may contain more than one).
  • Form_Url – URLs for the agency to find forms from the agency (may contain more than one).

For each of these URLs, the following sub-data elements are returned:

  • Url – The URL to the web page.
  • Description – A description of the URL.
  • Language – Whether the web page located at the URL is in English (en) or Spanish (es).

Agency Relationships

Additionally, the directory API returns information on the hierarchical relationship between federal agencies.

  • Parent – The parent of the agency. such as the Department of the Treasury for the Internal Revenue Service.
  • Child – Any children departments or agencies for the agency. such as the Census Bureau for the Department of Commerce (may contain more than one of these).
  • Alt_Language – The record for the agency in Spanish, if the record is in English, and vice versa.

For each of these relationships, the following sub-data elements are returned for the related agency:

  • Id – A unique identifier for each directory record
  • Name – The name of the agency.
  • URI – The URL to access the agency’s complete directory record via the API.
  • For Alt_Language only, Language – Whether the alternate language record is in English (en) or Spanish (es).

Back to Top

API Methods

As of version 2.0, the methods of the Federal Agency Directory API are broken down into two categories. The first category simply returns a list of agency records. The second category returns a hierarchical structure of the agency records, making it easy to form a tree. The tree can show that the Food and Drug Administration is part of the Department of Health and Human Services. This is just one example.

API Methods That Return A List of Agency Records

Contacts

Contacts is a general purpose call that, by default, will return all of the agency directory records. However, you can pass parameters into contacts that allow you to filter the records returned by the API in powerful ways.

Parameters

query_filter – Return only agency directory records that meet the criteria you enter into this parameter. In general, the filter takes the form of {field_name}::{value}[|{field_name}::{value}]*. Additionally, for names, you can perform substring searches by surrounding {value} with asterixis.

For example, if you want to return all agencies that have the word “commission” in their title, you can use a query_filter of name::*commission*. Likewise, if you want to find all commissions who have their main address in Virginia, you can use a query_filter of: name::*commission*|state::VA

See the data model above for a list of field names that you can query on.

result_filter – Return only the fields listed here (separated by |) as opposed to every field in each directory record. For example, use a result_filter of name|phone to return only names and phone numbers.

See the data model above for a list of field names that you can specify be returned.

sort – Allows you to specify the sort order of the returned agency directory records. For example, use a sort of name to sort the results by the agency’s name. You can also cause the sort to go in descending order by prepending the field name with a -, such as -name.

See the data model above for a list of field names that you can sort the results on.

Back to Top

/contacts/tree/independent

The independent method will return every agency record that has no parent and no child, such as the National Railroad Passenger Corporation.

/contacts/tree

The tree method returns every agency record, and, optionally, includes sub-agencies as part of their parent agency’s record.

Paramaters

include_descendants - Set to true if you want the API to return the descendents directly as part of their parent agency’s record.

/contacts/tree/dependent

The dependent method returns every agency record that has sub-agencies, and, optionally, includes sub-agencies as part of their parent agency’s record.

Parameters

include_descendants - Set to true if you want the API to return the descendents directly as part of their parent agency’s record.

/contact/{identifier}/tree/sibling

The sibling method will return all of the agency records that are siblings to the agency represented by the id specified in the REST URL. It will also return the record for the id specified as well.  

The only difference between the result format of the sibling method and the more generic contacts method is that the siblings method does not return the child and parent data elements as part of it’s results.

For example, if you request the sibling agencies for the U.S. Botanic Garden (id 49108), the API will return records for both the U.S. Botanic Garden and the U.S. Capitol Visitor Center, as both of these agencies are part of the Architect of the Capitol.

If you desired the results in JSON format, the API call for this query would look like the following:
http://www.usa.gov/api/USAGovAPI/contacts.json/contact/49108/tree/sibling

Back to Top

Sample Results For These Methods

For API methods that return a list of directory records, the API will return an array of objects, such as:

The API will return an array of objects, such as:

{
   "Contact":[
      {
         "Id":"52663",
         "URI":"http://www.usa.gov/api/USAGovAPI/contacts.json/contact/52663",
         "Language":"en",
         "Name":"U.S. Access Board",
         "Source_Url":"http://www.usa.gov/directory/federal/us-access-board.shtml",
         "Street1":"1331 F Street, NW",
         "Street2":"Suite 1000",
         "City":"Washington",
         "StateTer":"DC",
         "Zip":"20004-1111",
         "Synonym":[
            "Access Board"
         ],
         "Phone":[
            "202-272-0080"
         ],
         "Tollfree":[
            "800-872-2253"
         ],
         "TTY":[
            "202-272-0082",
            "800-993-2822"
         ],
         "Email":"info@access-board.gov",
         "Contact_Url":[
            {
               "Url":"http://www.access-board.gov/contact.htm",
               "Description":"Contact the U.S. Access Board ",
               "Language":"en"
            },
            {
               "Url":"http://www.access-board.gov/contact.htm#email",
               "Description":"E-mail Directory",
               "Language":"en"
            },
            {
               "Url":"http://www.access-board.gov/contact.htm#Phone",
               "Description":"Phone Directory",
               "Language":"en"
            },
            {
               "Url":"http://www.access-board.gov/enforcement/filing.htm",
               "Description":"File an Accessibility Complaint",
               "Language":"en"
            }
         ],
         "Web_Url":[
            {
               "Url":"http://www.access-board.gov/",
               "Description":"U.S. Access Board ",
               "Language":"en"
            }
         ],
         "In_Person_Url":[
            {
               "Url":"http://www.access-board.gov/contact.htm#Location",
               "Description":"Map and Directions",
               "Language":"en"
            }
         ],
         "Description":"The Access Board is an independent federal agency devoted to accessibility for people with disabilities. The Board develops and maintains design criteria for the built environment, transit vehicles, telecommunications equipment, and for electronic and information technology. ",
         "Alt_Language":[
            {
               "Id":"50175",
               "URI":"http://www.usa.gov/api/USAGovAPI/contacts.json/contact/50175",
               "Name":"Consejo de Acceso de Estados Unidos",
               "Language":"es"
            }
         ]
      },
      {
         "Id":"61787",
         "URI":"http://www.usa.gov/api/USAGovAPI/contacts.json/contact/61787",
         "Language":"en",
         "Name":"Medicaid and CHIP Payment and Access Commission",
         "Source_Url":"http://www.usa.gov/directory/federal/medicaid-chip-payment-access-commission.shtml",
         "Street1":"1800 M Street, NW",
         "Street2":"Suite 350N",
         "City":"Washington",
         "StateTer":"DC",
         "Zip":"20036",
         "Phone":[
            "202-273-2460"
         ],
         "Email":"webmaster@macpac.gov",
         "Web_Url":[
            {
               "Url":"http://www.macpac.gov",
               "Description":"Medicaid and CHIP Payment and Access Commission ",
               "Language":"en"
            }
         ]
      }
   ]
}

Back to Top

If you set include_descendents to true in the tree or descendants methods, parent agencies will include an array called "Contact" with their child agency records, such as in this snippet:

{
   "Contact":[
      {
         "Id":"49015",
         "URI":"http://www.usa.gov/api/USAGovAPI/contacts.json/contact/49015",
         "Language":"en",
         "Name":"U.S. Department of Agriculture (USDA)",
         "Source_Url":"http://www.usa.gov/directory/federal/department-of-agriculture.shtml",
         "Street1":"1400 Independence Ave., S.W.",
         "City":"Washington",
         "StateTer":"DC",
         "Zip":"20250",
         "Synonym":[
            "Agriculture Department",
            "Department of Agriculture"
         ],
         "Phone":[
            "202-720-2791"
         ],
         "Contact_Url":[
            {
               "Url":"http://usda.gov/wps/portal/usda/usdahome?navid=CONTACT_US",
               "Description":"Contact the U.S. Department of Agriculture (USDA) ",
               "Language":"en"
            },
            {
               "Url":"http://www.fns.usda.gov/cnd/Contacts/StateDirectory.htm",
               "Description":"Child Nutrition Programs",
               "Language":"en"
            },
            {
               "Url":"http://www.fns.usda.gov/snap/contact_info/default.htm",
               "Description":"Food Stamps",
               "Language":"en"
            },
            {
               "Url":"http://www.fsis.usda.gov/Food_Safety_Education/USDA_Meat_&_Poultry_Hotline/index.asp",
               "Description":"Meat and Poultry Hotline",
               "Language":"en"
            },
            {
               "Url":"http://offices.sc.egov.usda.gov/employeeDirectory/app",
               "Description":"Employee Directory",
               "Language":"en"
            }
         ],
         "Web_Url":[
            {
               "Url":"http://www.usda.gov/wps/portal/usda/usdahome",
               "Description":"U.S. Department of Agriculture (USDA) ",
               "Language":"en"
            }
         ],
         "In_Person_Url":[
            {
               "Url":"http://www.rurdev.usda.gov/recd_map.html",
               "Description":"Rural Development Office Locator",
               "Language":"en"
            },
            {
               "Url":"http://apps.ams.usda.gov/FarmersMarkets/",
               "Description":"Farmers Markets Near You",
               "Language":"en"
            },
            {
               "Url":"http://offices.sc.egov.usda.gov/locator/app",
               "Description":"Find a Service Center Near You",
               "Language":"en"
            }
         ],
         "Description":"The Department of Agriculture provides leadership on food, agriculture, natural resources, and related issues.",
         "Alt_Language":[
            {
               "Id":"50072",
               "URI":"http://www.usa.gov/api/USAGovAPI/contacts.json/contact/50072",
               "Name":"Departamento de Agricultura",
               "Language":"es"
            }
         ],
         "Contact":[
            {
               "Id":"48012",
               "URI":"http://www.usa.gov/api/USAGovAPI/contacts.json/contact/48012",
               "Language":"en",
               "Name":"Center for Nutrition Policy and Promotion (CNPP)",
               "Source_Url":"http://www.usa.gov/directory/federal/center-for-nutrition-policy-and-promotion.shtml",
               "Street1":"3101 Park Center Dr., 10th Floor",
               "City":"Alexandria",
               "StateTer":"VA",
               "Zip":"22302-1594",
               "Phone":[
                  "703-305-7600"
               ],
               "Contact_Url":[
                  {
                     "Url":"http://www.cnpp.usda.gov/contacts.htm",
                     "Description":"Contact the Center for Nutrition Policy and Promotion (CNPP) ",
                     "Language":"en"
                  }
               ],
               "Web_Url":[
                  {
                     "Url":"http://www.cnpp.usda.gov/",
                     "Description":"Center for Nutrition Policy and Promotion (CNPP) ",
                     "Language":"en"
                  },
                  {
                     "Url":"http://www.choosemyplate.gov/",
                     "Description":"",
                     "Language":"en"
                  }
               ],
               "Description":"The USDA Center for Nutrition Policy and Promotion (CNPP) works to improve the health and well-being of Americans by developing and promoting dietary guidance that links scientific research to the nutrition needs of consumers."
            }
         ]
      }
   ]
}

For a complete list of fields returned in the json, see the data model description above. Please note that any field that contains more than one item in it (such as synonyms), is returned as an array and noted in the data model description.

We encourage you to try out the interactive documentation to learn more.

Back to Top

API Methods That Return Agency Records in a Tree Form

These methods return agency records in a hierarchical data structure. In this way, you do not have to manually recreate the hierarchy yourself using the contacts method.

/contact/{identifier}/tree/parent

The parent method returns the record of the parent agency specified in the REST URL and will continue up the agency hierarchy until the root agency is returned. Additionally, the record for the id specified will also be returned.

For example, if you request the parent tree for the Administration for Native Americans (agency id 49064) , the API will return a tree structure whose head is the U.S.  Department of Health and Human Services, with a child record for the Administration for Children and Families, which will then have a child record for the Administration of Native Americans.

With JSON-formatted results, this call would be made with this URL:  http://www.usa.gov/api/USAGovAPI/contacts.json/contact/49064/tree/parent

Likewise, if you request the parent tree for the Administration for Children and Families (agency id 47994), the API will return a tree structure whose head is the U.S. Department of Health and Human Services, with a child record for the Administration for Children and Families.  However, the structure will end at that point instead of continuing down the agency hierarchy.

With JSON-formatted results, this call would be made with this URL:  http://www.usa.gov/api/USAGovAPI/contacts.json/contact/47994/tree/parent

/contact/{identifier}/tree/descendant

The descendant method will return a tree with the agency specified in the REST URL at it’s head. It will include all of the agency's sub-agencies as children. The tree will then continue in this fashion until the agencies with no children are returned.

For example, if you request the descendant tree of the Administration for Children and Families (agency id 47994), the API will return a tree structure with the record for the Administration for Children and Families at it’s head. There would then be child record for the Administration of Native Americans, since that agency is a subagency of the Administration for Children and Families.

With JSON-formatted results, this call would be made with this URL: http://www.usa.gov/api/USAGovAPI/contacts.json/contact/47994/tree/descendant

Likewise, if you request the descendant tree of the U.S. Department of Health and Human Services (agency id 49021), the API will return a tree structure with the U.S. Department of Health and Human Services record at it’s head, and have 15 child records for each of the sub-agencies.  The tree will continue in this manner until the entire U.S. Department of Health and Human Services hierarchy of agencies is exposed.

With JSON-formatted results, this call would be made with this URL: http://www.usa.gov/api/USAGovAPI/contacts.json/contact/49021/tree/descendant

/contact/{identifier}/tree/branch

The branch method returns a tree that is the combination of the trees returned by the parent method and the descendant method for the id specified in the REST URL. With this one method, the API will return every parent and every descendant of a particular agency.

/contact/{identifier}

The contact/{identifier} method will return the single directory record represented by the id specified in the REST URL. There are no children records returned when using this method.

Back to Top

Sample Results For These Methods

For API methods that return a tree of directory records, the API will return an array of objects, such as:

{
  "Id": "49021",
  "URI": "http://www.usa.gov/api/USAGovAPI/contacts.json/contact/49021",
  "Language": "en",
  "Name": "U.S. Department of Health and Human Services (HHS)",
  "Source_Url": "http://www.usa.gov/directory/federal/department-of-health-and-human-services.shtml",
  "Street1": "200 Independence Avenue, S.W.",
  "City": "Washington",
  "StateTer": "DC",
  "Zip": "20201",
  "Synonym": [
    "Health and Human Services Department",
    "Department of Health and Human Services"
  ],
  "Contact_Url": [
    {
      "Url": "http://www.hhs.gov/contactus.html",
      "Description": "Contact the U.S. Department of Health and Human Services (HHS) ",
      "Language": "en"
    },
    {
      "Url": "http://www.acf.hhs.gov/acf_contact_us.html#state",
      "Description": "Child Support",
      "Language": "en"
    },
    {
      "Url": "http://www.acf.hhs.gov/programs/ofa/help",
      "Description": "Temporary Assistance for Needy Families (Welfare)",
      "Language": "en"
    },
    {
      "Url": "http://www.medicare.gov/ContactUs.asp",
      "Description": "Medicare",
      "Language": "en"
    },
    {
      "Url": "http://www.acf.hhs.gov/programs/ocs/liheap/about/contact_us.html",
      "Description": "Low Income Home Energy Assistance Program (LIHEAP)",
      "Language": "en"
    },
    {
      "Url": "https://cfo.gov/cfo-members/",
      "Description": "Employee Directory",
      "Language": "en"
    }
  ],
  "Web_Url": [
    {
      "Url": "http://www.hhs.gov/",
      "Description": "U.S. Department of Health and Human Services (HHS) ",
      "Language": "en"
    }
  ],
  "In_Person_Url": [
    {
      "Url": "http://eclkc.ohs.acf.hhs.gov/hslc/HeadStartOffices",
      "Description": "Head Start Program Locator",
      "Language": "en"
    }
  ],
  "Description": "The Department of Health and Human Services protects the health of all Americans and provides essential human services.",
  "Alt_Language": [
    {
      "Id": "50081",
      "URI": "http://www.usa.gov/api/USAGovAPI/contacts.json/contact/50081",
      "Name": "Departamento de Salud y Servicios Sociales – HHS",
      "Language": "es"
    }
  ],
  "Contact": [
    {
      "Id": "47994",
      "URI": "http://www.usa.gov/api/USAGovAPI/contacts.json/contact/47994",
      "Language": "en",
      "Name": "Administration for Children and Families (ACF)",
      "Source_Url": "http://www.usa.gov/directory/federal/administration-for-children--families.shtml",
      "Street1": "370 L'nfant Promenade, SW",
      "City": "Washington",
      "StateTer": "DC",
      "Zip": "20447",
      "Tollfree": [
        "1-888-289-8442 (Fraud Alert Hotline)"
      ],
      "Contact_Url": [
        {
          "Url": "http://www.acf.hhs.gov/programs/ana/about",
          "Description": "Contact the Administration for Children and Families (ACF) ",
          "Language": "en"
        },
        {
          "Url": "https://cfo.gov/cfo-members/",
          "Description": "Employee Directory",
          "Language": "en"
        },
        {
          "Url": "http://www.acf.hhs.gov/acf_contact_us.html#state",
          "Description": "Child Support",
          "Language": "en"
        },
        {
          "Url": "http://www.acf.hhs.gov/programs/ofa/help",
          "Description": "Temporary Assistance for Needy Families (Welfare)",
          "Language": "en"
        },
        {
          "Url": "http://www.childwelfare.gov/pubs/reslist/rl_dsp.cfm?rs_id=5&rate_chno=11-11172",
          "Description": "Report Child Abuse and Neglect",
          "Language": "en"
        },
        {
          "Url": "http://www.acf.hhs.gov/programs/ocs/liheap/about/contact_us.html",
          "Description": "Low Income Home Energy Assistance Program (LIHEAP)",
          "Language": "en"
        }
      ],
      "Web_Url": [
        {
          "Url": "http://www.acf.hhs.gov/",
          "Description": "Administration for Children and Families (ACF) ",
          "Language": "en"
        }
      ],
      "In_Person_Url": [
        {
          "Url": "http://eclkc.ohs.acf.hhs.gov/hslc/HeadStartOffices",
          "Description": "Head Start Program Locator",
          "Language": "en"
        },
        {
          "Url": "http://www.acf.hhs.gov/programs/cse/extinf.html",
          "Description": "Child Support Enforcement in Your State",
          "Language": "en"
        }
      ],
      "Description": "The ACF funds state, territory, local, and tribal organizations to provide family assistance (welfare), child support, child care, Head Start, child welfare, and other programs relating to children and families.",
      "Alt_Language": [
        {
          "Id": "50101",
          "URI": "http://www.usa.gov/api/USAGovAPI/contacts.json/contact/50101",
          "Name": "Administración de Asuntos de Niños y Familias",
          "Language": "es"
        }
      ],
      "Contact": [
        {
          "Id": "49064",
          "URI": "http://www.usa.gov/api/USAGovAPI/contacts.json/contact/49064",
          "Language": "en",
          "Name": "Administration for Native Americans",
          "Source_Url": "http://www.usa.gov/directory/federal/administration-for-native-americans.shtml",
          "Street1": "2nd Floor, West Aerospace Center",
          "Street2": "370 L'Enfant Promenade, SW",
          "City": "Washington",
          "StateTer": "DC",
          "Zip": "20447-0002",
          "Tollfree": [
            "877-922-9262"
          ],
          "Email": "anacomments@acf.hhs.gov",
          "Contact_Url": [
            {
              "Url": "http://www.acf.hhs.gov/programs/ana/about",
              "Description": "Contact the Administration for Native Americans ",
              "Language": "en"
            }
          ],
          "Web_Url": [
            {
              "Url": "http://www.acf.hhs.gov/programs/ana/",
              "Description": "Administration for Native Americans ",
              "Language": "en"
            }
          ],
          "Description": "The Administration for Native Americans promotes self-sufficiency and cultural preservation for Native Americans by providing social and economic development opportunities through financial assistance, training, and technical assistance.",
          "Alt_Language": [
            {
              "Id": "50125",
              "URI": "http://www.usa.gov/api/USAGovAPI/contacts.json/contact/50125",
              "Name": "Oficina de Asuntos Nativo Americanos",
              "Language": "es"
            }
          ]
        }
      ]
    }
  ]
}

Terms of Service

By using this data, you agree to the Terms of Service.

Back to Top

The Tax Filing

Tax filing Index A Archer MSAs, Archer MSAs, Employment taxes. Tax filing Assistance (see Tax help) C Contributions to FSA, Contributions to an FSA HRA, Contributions to an HRA HSA, Contributions to an HSA MSA, Contributions to an MSA D Death of HSA holder, Death of HSA Holder MSA holder, Death of the Archer MSA Holder Distributions from FSA, Distributions From an FSA HRA, Distributions From an HRA HSA, Distributions From an HSA MSA, Distributions From an MSA E Employer participation FSA, Employer Participation HRA, Employer Participation HSA, Employer Participation MSA, Employer Participation F Flexible Spending Arrangements Grace Period, Health FSA – grace period. Tax filing Flexible spending arrangements, Flexible Spending Arrangements (FSAs), Employer Participation Balance in, Balance in an FSA Contributions to, Contributions to an FSA Distributions from, Distributions From an FSA Qualifying for, Qualifying for an FSA When to contribute, When To Contribute Form 5329, Excess contributions. Tax filing , Excess contributions. Tax filing 5498–SA, Form 8889. Tax filing , Reporting Contributions on Your Return 8853, Additional tax. Tax filing , Filing Form 8853 8889, Form 8889. Tax filing , Additional tax. Tax filing , Filing Form 8889 Free tax services, Free help with your tax return. Tax filing H Health plans, high deductible, High deductible health plan (HDHP). Tax filing , High deductible health plan (HDHP). Tax filing Health reimbursement arrangements, Health Reimbursement Arrangements (HRAs), Employer Participation Balance in, Balance in an HRA Contributions to, Contributions to an HRA Distributions from, Distributions From an HRA Qualifying for, Qualifying for an HRA Health savings accounts, Health Savings Accounts (HSAs), Employment taxes. Tax filing Balance in, Balance in an HSA Contributions to, Contributions to an HSA Deemed distributions, Deemed distributions from HSAs. Tax filing Distributions from, Distributions From an HSA Last-month rule, Last-month rule. Tax filing Partnerships, Reporting Contributions on Your Return Qualifying for, Qualifying for an HSA Rollovers, Rollovers S corporations, Reporting Contributions on Your Return When to contribute, When To Contribute Help (see Tax help) High deductible health plan, High deductible health plan (HDHP). Tax filing , High deductible health plan (HDHP). Tax filing M Medical expenses, qualified, Qualified medical expenses. Tax filing , Qualified medical expenses. Tax filing , Qualified medical expenses. Tax filing , Qualified medical expenses. Tax filing Medical savings accounts, Medical Savings Accounts (MSAs), Medicare Advantage MSAs Balance in, Balance in an Archer MSA Contributions to, Contributions to an MSA Deemed distributions, Deemed distributions from Archer MSAs. Tax filing Distributions from, Distributions From an MSA Medicare Advantage MSAs, Medicare Advantage MSAs Qualifying for, Qualifying for an Archer MSA When to contribute, When To Contribute Medicare Advantage MSAs, Medicare Advantage MSAs P Preventive care, High deductible health plan (HDHP). Tax filing Publications (see Tax help) Q Qualified HSA funding distribution, Qualified HSA funding distribution. Tax filing T Tax help, How To Get Tax Help Testing period Last-month rule, Testing period. Tax filing Qualified HSA funding distribution, Funding distribution – testing period. Tax filing TTY/TDD information, How To Get Tax Help Prev  Up     Home   More Online Publications