Accessing suppressed Tribal data via the API
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Accessing suppressed Tribal data via the API

Tribes and Tribal organizations have the option, per 2 CFR 200.512(b)(2), to suppress their Single Audit data.

For Tribes and Tribal organizations who choose to protect their data, the API will show is_public in the /general endpoint set to False.

If you believe you should have access to these audits, you will need to request a copy of the Tribal API Access Agreement via the helpdesk.

Working with the data

Your Tribal access API key will let you request a one-time access token. You'll use this token to download suppressed reports.

Once you have your token, use the instructions below to complete your API set-up:

Step 1: Fetch data about a submission

This step retrieves data about a submission based on the provided report ID.

Endpoint

GET /general?report_id=eq.{report_id}

Parameters

Headers

Response

Code

import requests

def fetch_submission_data(report_id):
    url = '/api.fac.gov/general?report_id=eq.{report_id}'
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        submission_data = response.json()
        return submission_data

Step 2: Request file access

After fetching submission data, you can request access to download the associated file.

Endpoint

POST /api.fac.gov/rpc/request_file_access

Parameters

Headers

Response

Code

import json
import requests

def request_file_access(report_id):
    url = '/api.fac.gov/rpc/request_file_access'
    headers = {
        'content-Profile': 'admin_api_v1_1_0',
        'x-api-key': f'{API_KEY}',
        'Content-Type': 'application/json',
           }
    payload = json.dumps({
        "report_id": f'{report_id}'
    })
    response = requests.post(url, headers=headers, data=payload)
    if response.status_code == 200:
        access_info = response.json()
        # `access_info` is a JSON object containing
        # a one-time token needed to download a suppressed SAR.
        return access_info

Step 3: Download the file

Once you have the access information, you can use it to download the associated file. Use the access UUID that was retrieved in the last step to get the file.

Endpoint:

GET /app.fac.gov/dissemination/report/pdf/ota/{access_uuid}

Parameters

access_uuid (required): The access UUID obtained from the /request_file_access endpoint.

Headers

None required; this is a straight GET request to download a file.

Response

Other HTTP status codes indicate various error scenarios.

Code

import requests

##############################################
# Note we download the PDF from `app.fac.gov`,
# not from `api.fac.gov`.
##############################################
def download_file(access_info):
    access_uuid_value = access_info.get('access_uuid')
    url = '/app.fac.gov/dissemination/report/pdf/ota/{access_uuid_value}'
    payload = {}
    try:
        response = requests.get(url, headers=headers, data=payload)
        if response.status_code == 200:
            with open("downloaded_file.pdf", "wb") as pdf_file:
                pdf_file.write(response.content)
            print("File downloaded successfully.")
        else:
            print("Failed to download file. Status code:", response.status_code)
            print("Response content:", response.text)
    except Exception as e:
        print("Error occurred while downloading file:", e)

Notes

These temporary URLs can't be stored or cached. Every time you want to access a suppressed report via the API, you'll need to go through the steps outlined above.