Regulations.gov API

Overview

When Congress passes laws, federal agencies implement those laws through regulations. These regulations vary in subject, but include everything from ensuring water is safe to drink to setting health care standards. Regulations.gov is the place where users can find and comment on regulations. The APIs allow for users to find creative ways to present regulatory data. To learn more about the program visit the About Us page.

Getting Started

To begin using this API, you will need to register for an API Key below.

If you want to use commenting API, you MUST use the form below to register for an API key.

Loading signup form...

In order to enable commenting, please contact the Regulations.gov Help desk and provide the first 5 digits of your API key, organization name, organization full address, organization phone number, tax ID and the email address used to sign up for the key. You will be notified when your API key is ready for posting comments. In order to activate your API key, these data elements are required to run an entity validation search.

After registration, you will need to provide this API key in the X-Api-Key HTTP header with every API request.

HTTP Header Name	Description
X-Api-Key	API key from api.data.gov. For sample purposes, you can use `DEMO_KEY` as an API key.

Terms of Participation

The eRulemaking post Application Programming Interface (API), informally referred to as the Comment API, is provided as a convenience to facilitate the bulk upload of comments from a number of different commenters. The use of the Comment API requires a key, which may be obtained through the open GSA website.

By registering for, receiving and using a key to the Comment API, the key holder agrees to the following terms and conditions:

When developing interfaces for commenters who will submit comment language and/or attachments through the Comment API, the key holder will include in the interface:
1. A link to the same terms of participation and privacy notice that users encounter on the comment form for Regulations.gov, and
2. A link to the Federal Register notice or other specific document in Regulations.gov for which the key holder is collecting or facilitating comments to be delivered through the Comment API.
The key holder certifies that:
1. I will only submit comments through the Comment API that it has gathered through lawful means and that, to the best of the key holder’s knowledge, represent comments from real persons, and
2. It has not and will not submit comments of its own creation under fictitious or misappropriated identities or otherwise in violation of federal law.
The API key may be disabled if an API key holder is determined to have violated these Terms of Participation.

API Description

Regulations.gov offers a GET API for documents, comments, and dockets and a POST API for comments. These endpoints can be used for searching document, comments and dockets, and posting a comment.

Searching for documents

You can search for a list of documents based on the criteria passed by using the endpoint /v4/documents. The search operation supports full text keyword searches and filtering based on a number of available parameters.

Detailed information for a single document

In order to obtain more details about a single document, you can use the endpoint /v4/documents/{documentId}. A document is defined by one of the following types: Proposed Rule, Rule, Supporting & Related, or Other. Each document type has its own set of attributes, which vary based on the Agency posting the document. Another defining characteristic is if the document is part of a Rulemaking or Nonrulemaking Docket.

You can choose to include attachments using include parameter. Attachments are not included by default.

Searching for comments

You can search for a list of comments based on the criteria passed by using the endpoint /v4/comments. The search operation supports full text keyword searches and filtering based on a number of available parameters.

Detailed information for a single comment

In order to obtain more details about a single comment, you can use the endpoint /v4/comments/{commentId}. Each comment has its own set of attributes, which vary based on the Agency posting the comment. Another defining characteristic is if the comment is part of a Rulemaking or Nonrulemaking Docket.

You can choose to include attachments using include parameter. Attachments are not included by default.

Searching for dockets

A docket is an organizational folder containing multiple documents. Dockets can be searched using the endpoint: /v4/dockets.

Detailed information for a single docket

In order to obtain more details about a single docket, you can use the endpoint /v4/dockets/{docketId}. Each docket has its own set of attributes, which vary based on the Agency posting the docket. Another defining characteristic is if the docket is a Rulemaking or a Nonrulemaking Docket

Posting a comment

User can post a comment using the endpoint /v4/comments. User can post the comment using one of the following submitter types:

Individual
Organization
Anonymous

If user would like to attach files with their submission, user can get a presigned url for the amazon s3 bucket using the endpoint /v4/file-upload-urls

A submissionKey can be retrieved using /v4/submission-keys endpoint.

submissionType should be set to API.

Data Limitations

A recent GAO report expressed concerns over whether comment data is fully described to the public, including any limitations. Various aspects of the commenting process can create limitations for certain external users of public comment data and some data fields are managed solely by agencies. For agency-specific commenting practices, contact eRulemaking@gsa.gov. The Open API Specification document has been updated with information on agency configurable fields. For convenience, the data is also provided below in a concise format:

List of fields that are always publicly viewable on a comment

Here is the list of fields that is always available in the JSON response for a comment:

agencyId
comment
commentOnId
docketId
documentId - This field is returned as an Id of the document in the JSON response.
documentType
postedDate
receiveDate
restrictReason - if restrictReasonType is set to “Other”
restrictReasonType - if the document is restricted
reasonWithdrawn - if the comment has been withdrawn
title
trackingNbr
withdrawn

List of agency configurable comment fields

Agency configured fields can be updated by an agency at any point in time and made accessible or inaccessible in the JSON response of a comment. Here is the list of these fields:

city
country
docAbstract
firstName
govAgency
govAgencyType
lastName
legacyId
organization
pageCount
postmarkDate
stateProvinceRegion
subtype
zip

List of fields that are never publicly viewable on a comment

originalDocumentId
address1
address2
email
phone
fax

Post Comment API Validation

Common Validations for all comments

commentOnDocumentId, comment and submissionType are required fields.
If sendEmailReceipt is true, email field is required.
An emoji is not a valid character.
If a field has a maximum length requirement, the requirement is applied to both, the number of characters and the number of bytes.
submitterType field must be one of these allowed values: ANONYMOUS, INDIVIDUAL, ORGANIZATION.
submissionType field must be set to API.
Field value for comment must be less than or equals to 5000 characters/bytes.
Field value for email must be less than or equals to 100 characters/bytes.

Individual Comment Validations

firstName and lastName are required fields.
Field value for firstName and lastName must be less than or equals to 25 characters/bytes.
Field value for city, stateProvinceRegion, phone and country must be less than or equals to 50 characters/bytes.
Field value for zip field must have less than or equals to 10 characters/bytes.

Organization Comment Validations

organization and organizationType are required fields.
Field value for organization field must have less than or equals to 120 characters/bytes.

Examples

Searching for documents

Here are few example queries for searching documents:

Search for term water:

https://api.regulations.gov/v4/documents?filter[searchTerm]=water&api_key=DEMO_KEY

Filter documents by a specific date:

https://api.regulations.gov/v4/documents?filter[postedDate]=2020-09-01&api_key=DEMO_KEY

Filter documents by a date range:

https://api.regulations.gov/v4/documents?filter[postedDate][ge]=2020-09-01&filter[postedDate][le]=2020-09-01&api_key=DEMO_KEY

Search for a documentId:

https://api.regulations.gov/v4/documents?filter[searchTerm]=FDA-2009-N-0501-0012&api_key=DEMO_KEY

Sort documents by posted date in asc:

https://api.regulations.gov/v4/documents?sort=postedDate&api_key=DEMO_KEY

Sort documents by posted date in desc:

https://api.regulations.gov/v4/documents?sort=-postedDate&api_key=DEMO_KEY

Detailed information for a single document

There are few ways a user can query documents endpoint to retrieve detailed information for a document.

Get document details without attachments:

https://api.regulations.gov/v4/documents/FDA-2009-N-0501-0012?api_key=DEMO_KEY

Get document details with attachments:

https://api.regulations.gov/v4/documents/FDA-2009-N-0501-0012?include=attachments&api_key=DEMO_KEY

Searching for comments

Here are few example queries for searching comments:

Search for term water:

https://api.regulations.gov/v4/comments?filter[searchTerm]=water&api_key=DEMO_KEY

Filter comments by a specific date:

https://api.regulations.gov/v4/comments?filter[postedDate]=2020-09-01&api_key=DEMO_KEY

Filter comments by a date range:

https://api.regulations.gov/v4/comments?filter[postedDate][ge]=2020-09-01&filter[postedDate][le]=2020-09-01&api_key=DEMO_KEY

Search for a commentId:

https://api.regulations.gov/v4/comments?filter[searchTerm]=HHS-OCR-2018-0002-5313&api_key=DEMO_KEY

Sort comments by posted date in asc:

https://api.regulations.gov/v4/comments?sort=postedDate&api_key=DEMO_KEY

Sort comments by posted date in desc:

https://api.regulations.gov/v4/comments?sort=-postedDate&api_key=DEMO_KEY

Retrieve all comments for a docket where number of comments is less than 5000:
- Step 1: Get all documents for the docketId FAA-2018-1084:
```
https://api.regulations.gov/v4/documents?filter[docketId]=FAA-2018-1084&api_key=DEMO_KEY
```
  It returns two documents, FAA-2018-1084-0001 and FAA-2018-1084-0002. Each document metadata includes an objectId attribute.
- Step 2: Get all comments for each document using objectId:
```
https://api.regulations.gov/v4/comments?filter[commentOnId]=0900006483a6cba3&api_key=DEMO_KEY
```
  The above request returns a list of comments for document FAA-2018-1084-0001.
  
  Note: Step 2 should be repeated for FAA-2018-1084-0002 in the above example.
Retrieve all comments for a docket where number of comments is greater than 5000:
- Step 1: Get all documents for the docketId EOIR-2020-0003:
```
https://api.regulations.gov/v4/documents?filter[docketId]=EOIR-2020-0003&api_key=DEMO_KEY
```
  The above query returns five documents where four documents are Supporting & Related Material documents and one document is a Proposed Rule. Response for the above request includes an attribute objectId for each document and its set to 09000064846eebaf for the Proposed Rule, EOIR-2020-0003-0001.
- Step 2: Get all comments for each document using objectId:
```
https://api.regulations.gov/v4/comments?filter[commentOnId]=09000064846eebaf&api_key=DEMO_KEY
```
  The above request returns a list of comments for document EOIR-2020-0003-0001, the only Proposed Rule in the docket. totalElements under meta attribute shows that this document has total 88,061 comments.
  
  Note: Step 2 should be repeated for each document.
- Step 3: Page through the first set of 5000 documents:
```
https://api.regulations.gov/v4/comments?filter[commentOnId]=09000064846eebaf&page[size]=250&page[number]=N&sort=lastModifiedDate,documentId&api_key=DEMO_KEY
```
  The first 5000 documents can be retrieved using the query above and paging through the results where N is the page number between 1 and 20. Please note we are sorting the results by lastModifiedDate to ensure we can filter our data by lastModifiedDate later. On the last page of this set, please note the lastModifiedDate of the last document. In our case, EOIR-2020-0003-5548 is the last document on page 20 and the lastModifiedDate attribute of the document is 2020-08-10T15:58:52Z. We will be filtering the data in the next step using this date.
- Step 4: Page through the next set of 5000 documents:
```
https://api.regulations.gov/v4/comments?filter[commentOnId]=09000064846eebaf&filter[lastModifiedDate][ge]=2020-08-10 11:58:52&page[size]=250&page[number]=N&sort=lastModifiedDate,documentId&api_key=DEMO_KEY
```
  The next 5000 documents can be retrieved using the query above and paging through the results where N is the page number between 1 and 20.
  
  The lastModifiedDate attribute of the last document in the first set (Step 3) was 2020-08-10T15:58:52Z. This date translates to 2020-08-10 11:58:52 in Eastern time. Running the above query should return all documents where lastModifiedDate is greater than or equal to 2020-08-10T15:58:52Z. Its important to note that we are running a “greater than or equal to” query to ensure we do not miss any documents where last modified date is 2020-08-10T15:58:52Z.
  
  On the last page of this set, please note the lastModifiedDate of the last document and repeat.
  
  Note: Step 4 should be repeated for as many times as needed to retrieve all 88,061 comments.

Detailed information for a single comment

There are few ways a user can query comments endpoint to retrieve detailed information for a comment:

Get comment details without attachments:

https://api.regulations.gov/v4/comments/HHS-OCR-2018-0002-5313?api_key=DEMO_KEY

Get comment details with attachments:

https://api.regulations.gov/v4/comments/HHS-OCR-2018-0002-5313?include=attachments&api_key=DEMO_KEY

Searching for dockets

Here are few example queries for searching dockets:

Search for term water:

https://api.regulations.gov/v4/dockets?filter[searchTerm]=water&api_key=DEMO_KEY

Search for a docketId:

https://api.regulations.gov/v4/dockets?filter[searchTerm]=EPA-HQ-OAR-2003-0129&api_key=DEMO_KEY

Filter dockets by multiple agencyIds:

https://api.regulations.gov/v4/dockets?filter[agencyId]=GSA,EPA&api_key=DEMO_KEY

Sort dockets by title in asc order:

https://api.regulations.gov/v4/dockets?sort=title&api_key=DEMO_KEY

Sort dockets by title in desc order:

https://api.regulations.gov/v4/dockets?sort=-title&api_key=DEMO_KEY

Detailed information for a single docket

To retrieve detailed information on a docket, the following query can be used:

https://api.regulations.gov/v4/dockets/EPA-HQ-OAR-2003-0129?api_key=DEMO_KEY

Posting a comment

Posting an anonymous comment without attachment:

POST https://api.regulations.gov/v4/comments {
  "data": {
    "attributes": {
      "commentOnDocumentId":"FDA-2009-N-0501-0012",
      "comment":"test comment",
      "submissionType":"API",
      "submitterType":"ANONYMOUS"
    },
    "type":"comments"
  }
}

Note: No submission key is needed for comments with no attached files.

Posting a comment with attachment:

Step 1: Get a submission key:

POST https://api.regulations.gov/v4/submission-keys {
  "data": {
    "type":"submission-keys"
  }
}

Step 2: Get presigned url for each attachment:

POST https://api.regulations.gov/v4/file-upload-urls {
  "data": {
    "type":"file-upload-urls",
    "attributes": {
      "fileName":"test.jpg",
      "submissionKey":"kex-d31z-fe04",
      "contentType":"image/jpeg"
    }
  }
}

Step 3: Upload binaries to presigned url

Step 4: Submit your comment

POST https://api.regulations.gov/v4/comments {
  "data": {
    "attributes": {
      "commentOnDocumentId":"FDA-2009-N-0501-0012",
      "comment":"test comment",
      "submissionType":"API",
      "submissionKey":"kex-d31z-fe04",
      "submitterType":"ANONYMOUS",
      "files":[ "test.jpg" ]
    },
    "type":"comments"
  }
}

Posting a comment with agency category:

Step 1: Get agency categories for agency:

https://api.regulations.gov/v4/agency-categories?filter[acronym]=FDA&api_key=DEMO_KEY

Step 2: Submit your comment with category:

POST https://api.regulations.gov/v4/comments {
  "data": {
    "attributes": {
      "commentOnDocumentId":"FDA-2009-N-0501-0012",
      "comment":"test comment",
      "submissionType":"API",
      "submitterType":"ANONYMOUS",
      "category":"Academia - E0007"
    },
    "type":"comments"
  }
}

Posting multiple submissions in a single comment:

To post a comment with attachment that carries 5 submissions, user should follow the following steps:

Step 1: Get a submission key:

POST https://api.regulations.gov/v4/submission-keys {
  "data": {
    "type":"submission-keys"
  }
}

Step 2: Get presigned url for the attachment with multiple submissions:

POST https://api.regulations.gov/v4/file-upload-urls {
  "data": {
    "type":"file-upload-urls",
    "attributes": {
      "fileName":"multipleSubmissions.pdf",
      "submissionKey":"kex-d31z-fe04",
      "contentType":"image/jpeg"
    }
  }
}

Step 3: Upload binaries to presigned url

Step 4: Submit your comment with

POST https://api.regulations.gov/v4/comments {
  "data": {
    "attributes": {
      "commentOnDocumentId":"FDA-2009-N-0501-0012",
      "comment":"test comment",
      "submissionType":"API",
      "submissionKey":"kex-d31z-fe04",
      "submitterType":"ANONYMOUS",
      "files":[ "multipleSubmissions.pdf" ],
      "numItemsReceived": 5
    },
    "type":"comments"
  }
}

OpenAPI Specification File

You can view the full details of this API in the OpenAPI Specification file available here: Open API specification file for the Regulations.gov API

Frequently Asked Questions

I am not seeing all fields returned by v3/documents endpoint in v4/documents endpoint. How do I access this information?

Our v3 API had a single search endpoint which returned information about documents, comments and dockets. To streamline our data, we have split our search into three endpoints:

Document Search
Comment Search
Docket Search

Further, some data that could be retrieved using search in v3 has now been moved under details endpoint. For example, you can retrieve RIN for a docket using /dockets/{docketId} endpoint. The rin is not returned by /documents endpoint anymore.

How do I get document status from the new `/documents` endpoint?

The new /v4/documents carries a withdrawn field. This is a boolean field. If set to true, the document is withdrawn otherwise it’s a posted document.

There are strict pagination limits in v4. How do I retrieve all comments in a docket posted on the same day if the number of comments is greater than 2500?

We have added an example that shows how to retrieve more than 5000 comments on a docket. Please see the example section.

Please note the new parameter lastModifiedDate is in beta and may be removed when we have a permanent bulk download solution available.

I submitted a comment, but I am unable to find it on regs. What happened to my comment?

Comments created via API are not made available in Regulations.gov right away. Agencies need to approve before the newly created comment can be posted out to Regulations.gov.

I am seeing 400 errors from commenting API. What am I doing wrong?

Please make sure you are setting Content-Type to application/vnd.api+json in request header.

What is DEMO_KEY api key?

As indicated by name, DEMO_KEY should only be used for demonstration purposes. We have added this api_key to our examples to make it easier for users to copy/paste the urls. It should not be used for anything more than exploring our APIs.

What is the staging API url?

Users should be able to access our staging API at https://api-staging.regulations.gov. Please use this environment for testing purposes.

I have an API key. How many requests can I make per hour and how do I know I am about to reach my request limit?

Please review https://api.data.gov/docs/rate-limits/ for information on rate limits. Commenting API is restricted to 50 requests per minute with a secondary limit of 500 requests per hour.

Can I request rate limit increases for my keys?

GSA may grant a rate limit increase on the GET keys for an indefinite period. Such requests must establish the need to justify the rate limit increases. Each submission will be reviewed and considered on a case-by-case basis. GSA is unable to increase the rate limits for POST API keys upon requests at this time. However, the current POST API key holders can request one additional key without going through the validation process again.

API Calls

Contact Us

If you have any questions or would like to provide feedback, please contact Regulations.gov Help desk.

Overview

Getting Started

Terms of Participation

API Description

Searching for documents

Detailed information for a single document

Searching for comments

Detailed information for a single comment

Searching for dockets

Detailed information for a single docket

Posting a comment

Data Limitations

List of fields that are always publicly viewable on a comment

List of agency configurable comment fields

List of fields that are never publicly viewable on a comment

Post Comment API Validation

Common Validations for all comments

Individual Comment Validations

Organization Comment Validations

Examples

Searching for documents

Detailed information for a single document

Searching for comments

Detailed information for a single comment

Searching for dockets

Detailed information for a single docket

Posting a comment

OpenAPI Specification File

Frequently Asked Questions

I am not seeing all fields returned by v3/documents endpoint in v4/documents endpoint. How do I access this information?

How do I get document status from the new /documents endpoint?

There are strict pagination limits in v4. How do I retrieve all comments in a docket posted on the same day if the number of comments is greater than 2500?

I submitted a comment, but I am unable to find it on regs. What happened to my comment?

I am seeing 400 errors from commenting API. What am I doing wrong?

What is DEMO_KEY api key?

What is the staging API url?

I have an API key. How many requests can I make per hour and how do I know I am about to reach my request limit?

Can I request rate limit increases for my keys?

API Calls

Contact Us

How do I get document status from the new `/documents` endpoint?