The FCC has made an API available that ISPs can use to respond to fixed availability challenges. If responding in bulk via the API, providers can also use a single evidence file to respond to multiple challenges.
- API documentation:https://us-fcc.app.box.com/v/bdc-filer-api-spec, and the
- API swagger file: https://us-fcc.app.box.com/v/bdc-filer-api-swagger
- Sample BDCAPI script: https://github.com/FCC/bdcapi
This article provides additional information and tips on how to use the API through use of a sample API script made publicly available (the "BDCAPI" package). This script is meant to demonstrate how an ISP could integrate with the BDC's API endpoints. While the script is fully functional and should allow an ISP to manage fixed challenge responses out-of-the-box, the code is intended as a proof of concept to allow interested parties to build their own API integrations.
To run the BDCAPI script, you will need to install Python version 3.8 or above with several additional packages. One approach is to install miniconda (https://docs.conda.io/en/main/miniconda.html) with an environment for Python 3.8 or higher.
Installing Prerequisites and BDCAPI Package
The simplest way to install the BDCAPI package requires that you first install the "pip" and "git" packages, then to install the "bdcapi" package directly from GitHub. From the Anaconda / miniconda command line interface, install the prerequisites by running the following command:
conda install pip git
After the "pip" and "git" packages are installed, install the BDCAPI package from GitHub by running the following command:
pip install git+https://github.com/FCC/bdcapi
This will install some additional prerequisites, including the "click", "pandas", "numpy", "PyYAML", and "requests" packages. You can confirm that the BDCAPI script was installed correctly by running the following command:
You should then see an output like the following:
$ bdcapi --help
Usage: bdcapi [OPTIONS] COMMAND [ARGS]...
--version Show the version and exit.
--python-version Show the version and exit.
-h, --help Show this message and exit.
Initializing the BDCAPI Script
After confirming successful installation of the BDCAPI script, you may configure the script for later use. Please note that this step is optional, and you may always specify command-line options to provide the username, API token, and other parameters at the time that you run the BDCAPI script. To perform the initialization / setup process, run the following command:
After running this command, you will be prompted to enter the BDC Base URL (i.e., https://bdc.fcc.gov/), your BDC username and 44-character API token, and other default parameters that will be used when you run the BDCAPI script.
To obtain an API token, please login to the BDC system, click on the "Manage API Access" link, and then click the "Generate" button in the Token section of the page.
Preparing Files for the BDCAPI Script
After installing all required packages and optionally configuring the script, you should prepare your data file. Specifically, you should prepare:
- A CSV file that contains the list of the challenge_id values that you are ready to take action on, with a header row that identifies that column with the header "challenge_id" (or whatever column name you specified during the configuration step)
- Alternatively, you can specify a different column name with the --challenge-file-column command line option
Working with the BDC API Script
At any point, you can get help details by calling the following:
or you may get additional help details for each given command by calling the following:
bdcapi COMMAND --help
Example command for submitting bulk initial responses:
bdcapi submit-bulk-initial-response --frn 0032176356 --evidence-file challenge_evidence_file.pdf Dispute virginia_challenges_to_dispute.csv
Example command for submitting bulk final responses:
bdcapi submit-bulk-final-response Dispute virginia_challenges_to_dispute.csv 1 Yes
Example command for reverting bulk initial responses:
bdcapi revert-bulk-initial-response virginia_challenges_to_dispute.csv
Example command for reverting bulk final responses:
bdcapi revert-bulk-final-response virginia_challenges_to_dispute.csv
Example command for certifying bulk responses:
bdcapi certify-bulk-response virginia_challenges_to_dispute.csv Remove "Jonathan McCormack" "Certification Officer" "firstname.lastname@example.org" "202-555-1234"
Responding when Resolution Has Been Reached with the Challenger
To respond to challenges for which you and the challenger have reached an agreement or resolution that your data are accurate and require no revisions, you should create a CSV file with the list of those challenges and then use that file with the BDCAPI script's bulk-submit-initial-response command with a response_type of Dispute (along with whatever PDF evidence file you decide to include). You should then be able to call the bulk-submit-final-response command with a response_type of Dispute, identify the appropriate resolution_code value and identify that the challenger_concurrence is Yes. At that point, the challenges will be sent for FCC adjudication, and FCC staff should be able to adjudicate those consistent with the mutual agreement between the provider and the challenger.
There are additional options and arguments for each of the above commands, and certain parameters are required (per the rules) only in certain circumstances. For example, the evidence file is required when submitting an initial response disputing the challenge but is optional when conceding or submitting a final response.
The BDCAPI script is setup to make requests with up to 1,000 challenge IDs at a time and pause in between to avoid hitting any rate limits. However, if you encounter issues with this volume, you can override this default to send fewer than 1,000 challenges at a time using the "--chunk-size" option (e.g., "--chunk-size 500").