The Do Not Call (DNC) Reported Calls Data API endpoint provides data every weekday about Do Not Call and robocall complaints reported to the 51±¾É«. This data consists of information , including the telephone number originating the unwanted call, the date the complaint was created, the time the call was made, the consumer’s city and state locations reported, the subject of the call, and whether the call was a robocall. None of the information about the reported calls is verified. This data is typically updated each weekday by about noon Eastern time. Weekend data is updated on Monday and holiday data is updated on the next business day. Recent weekly data is also available in CSV format.
For official aggregate Do Not Call data, please see the FTC’s and the annual National Do Not Call Registry Data Book.
More information about 51±¾É«APIs is on the 51±¾É«for Developers page.
List all DNC Complaints
GET /v0/dnc-complaints
Request
Path Parameters
(none)
Query Parameters
| Parameter | Type | Value |
|---|---|---|
| api_key | (string) | Required (unless provided in X-Api-Key header field). A valid api.data.gov API key. You can request an API key at . |
| created_date | (string) | Optional. Filter records by a specific date that complaints were created during. For example, show all complaints created on February 26, 2020: ?created_date="2020-02-26" Note: Date value must be enclosed in double-quotes. |
| created_date_from created_date_to |
(string) | Optional. Filter records by a range of dates/times that complaints were created. These filters must be used together. Can be combined with any one these filters: state, area_code or is_robocall. When combined with the state filter, an optional city filter can be added. For example, show all complaints created between February 26, 2020 and February 27, 2020: ?created_date_from="2020-02-26"&created_date_to="2020-02-27" Note: Date/time values must be enclosed in double-quotes. If only date values are provided, data will be filtered from midnight on created_date_from to 11:59:59pm on created_date_to. Time values can be specified using ISO-8601 format: "YYYY-MM-DD HH:MM:SS". |
| violation_date | (string) | Optional. Filter records by a specific date that unwanted calls were received during. For example, show all unwanted calls received on February 26, 2020: ?violation_date="2020-02-26" Note: Date value must be enclosed in double-quotes. |
| violation_date_from violation_date_to |
(string) | Optional. Filter records by a range of dates/times that unwanted calls were received during. For example, show all unwanted calls received between February 26, 2020 and February 27, 2020: ?violation_date_from="2020-02-26"&violation_date_to="2020-02-27" Note: Date/time values must be enclosed in double-quotes. If only date values are provided, data will be filtered from midnight on violation_date_from to 11:59:59pm on violation_date_to. Time values can be specified using ISO-8601 format: "YYYY-MM-DD HH:MM:SS". |
| state | (string) | Optional. Filter records by a state that complaints originated from. Can be combined with the city and created_date_from / created_date_to filters. For example, show all complaints originating from Idaho: ?state="Idaho" Note: Value that include spaces must be enclosed in double-quotes. |
| city | (string) | Optional. Filter records by a city that complaints originated from. This filter must be used together with the state filter. Can be combined with the created_date_from / created_date_to filters. For example, show all complaints originating from Phoenix, Arizona: ?state="Arizona"&city="Phoenix" Note: Value that include spaces must be enclosed in double-quotes. |
| area_code | (integer) | Optional. Filter records by the area code that complaints originated from. Can be combined with the created_date_from / created_date_to filters. For example, show all complaints originating from the 360 area code: ?area_code=360 |
| is_robocall | (string) | Optional. Filter by whether the unwanted call was a recorded message / robocall or not. Value must be either "true" or "false". Can be combined with the created_date_from / created_date_to filters. For example, only show complaints that were recorded messages / robocalls: ?is_robocall=true |
| sort_order | (string) | Optional. Sort direction to use with the sort_by parameter. DESC = Sort in descending order (default) ASC = Sort in ascending order. Example: ?sort_order=ASC |
| items_per_page | (integer) | Optional. Maximum number of records to include in JSON response. By default, the endpoint displays a maximum of 50 records per request – this is also the maximum value allowed. All non-empty responses include pagination metadata, which can be used to iterate over a large number of records, by sending a GET request for each page of records. Example: ?items_per_page=10 |
| offset | (integer) | Optional. Offset by a number of records, allowing a particular section of paginated results to be requested (use with the items_per_page parameter). Example: ?offset=10 |
Response Parameters
Response parameters are described at the end of this page.
Response Format
All responses are in JSON format. The JSON object structure loosely adheres to the spec. Possible responses:
| HTTP Status CODE | TYPE | Description |
|---|---|---|
| 200 | OK | List of DNC Complaint records (in JSON format). |
| 400 | Error | Request URL does not use HTTPS (which is required for all API requests). |
| 403 | Error | API key is missing or invalid. See api.data.gov for further details. |
| 404 | Error | The API endpoint requested could not be found. |
| 429 | Error | The rate limit has been exceeded for the API key provided. |
Example
List all DNC Complaints created on February 27, 2020, between 4:10am and 4:30am (showing most recent items first):
{
data: [
{
type: "dnc_complaint",
id: "2dae54c3d3c06d1960689139d39c3138",
attributes: {
company-phone-number: "6785050054",
created-date: "2020-02-27 04:23:11",
violation-date: "2020-02-26 16:00:00",
consumer-city: "Earlysville",
consumer-state: "Virginia",
consumer-area-code: "434",
subject: "Computer & technical support",
recorded-message-or-robocall: "N"
},
relationships: [ ],
meta: [ ],
links: {
self: "https://api.ftc.gov/v0/dnc-complaints/2dae54c3d3c06d1960689139d39c3138"
}
},
{
type: "dnc_complaint",
id: "2dae54c3d3c06d1960689139d39c2fb3",
attributes: {
company-phone-number: "5162681355",
created-date: "2020-02-27 04:13:57",
violation-date: "2020-02-25 00:00:00",
consumer-city: "Marion",
consumer-state: "Illinois",
consumer-area-code: "618",
subject: "Lotteries, prizes & sweepstakes",
recorded-message-or-robocall: "N"
},
relationships: [ ],
meta: [ ],
links: {
self: "https://api.ftc.gov/v0/dnc-complaints/2dae54c3d3c06d1960689139d39c2fb3"
}
}
],
meta: {
records-this-page: 2,
record-total: 2
},
links: {
self: "https://api.ftc.gov/v0/dnc-complaints?created_date_from=%222020-02-27%2004:10:00%22&created_date_to=%222020-02-27%2004:30:00%22"
}
}
Get a single DNC Complaint
GET /v0/dnc-complaints/{id}
Request
Path Parameters
| Parameter | Type | Value |
|---|---|---|
| {id} | (integer) | Required. A valid ID for a DNC Complaint record. |
Query Parameters
| Parameter | Type | Value |
|---|---|---|
| api_key | (string) | Required (unless provided in X-Api-Key header field). A valid api.data.gov API key. You can request an API key at . |
Response Parameters
Response parameters are described at the end of this page.
Response Format
All responses are in JSON format. The JSON object structure loosely adheres to the spec. Possible responses:
| HTTP Status CODE | TYPE | Description |
|---|---|---|
| 200 | OK | List of DNC Complaint records (in JSON format). |
| 400 | Error | Request URL does not use HTTPS (which is required for all API requests). |
| 403 | Error | API key is missing or invalid. See api.data.gov for further details. |
| 404 | Error | The API endpoint requested could not be found. |
| 429 | Error | The rate limit has been exceeded for the API key provided. |
Example
List DNC Complaints for ID = "2dae54c3d3c06d1960689139d39c3138" :
{
data: [
{
type: "dnc_complaint",
id: "2dae54c3d3c06d1960689139d39c3138",
attributes: {
company-phone-number: "6785050054",
created-date: "2020-02-27 04:23:11",
violation-date: "2020-02-26 16:00:00",
consumer-city: "Earlysville",
consumer-state: "Virginia",
consumer-area-code: "434",
subject: "Computer & technical support",
recorded-message-or-robocall: "N"
},
relationships: [ ],
meta: [ ],
links: {
self: "https://api.ftc.gov/v0/dnc-complaints/2dae54c3d3c06d1960689139d39c3138"
}
}
],
meta: {
records-this-page: 1,
record-total: 1
},
links: {
self: "none"
}
}
Response Parameters
| Parameter | Type | Value |
|---|---|---|
| data | (array) | An array of DNC Complaint record objects. |
| type | (string) | The record type (for this endpoint, the type is "dnc_complaint"). |
| id | (string) | The record ID. |
| attributes | (object) | An object containing the main data for this record. |
| company-phone-number | (string) | Optional (may be empty). The telephone number the unwanted call orignated from. |
| created-date | (string) | The date/time the complaint was created. Timestamp format is . Example: 1997-07-16T19:20:30+01:00 |
| violation-date | (string) | The date/time the unwanted call was received. Timestamp format is . |
| consumer-city | (string) | Optional (may be empty). The city reported by the consumer who created the complaint. |
| consumer-state | (string) | Optional (may be empty). The state reported by the consumer who created the complaint. |
| consumer-area-code | (string) | Optional (may be empty). The area code of the consumer that created the complaint. |
| subject | (string) | Optional (may be empty). The subject of the unwanted call. |
| recorded-message-or-robocall | (string) | Optional (may be empty). Indicates whether the unwanted call was a recorded message / robocall ("Y"), or not ("N"). |
| relationships | (array) | An array of other records related to this record. |
| meta | (array) | An array of metadata for this record. |
| links | (object) | An object containing links pertaining to this record. |
| self | (url) | The URL for this record. A valid "api_key" query parameter must be added to this URL, in order to access the record (see "Query Parameters" sections above for more details). |
| meta | (object) | An object containing metadata for the request itself, including pagination data. |
| records-this-page | (integer) | The number of records included in this response. |
| records-total | (integer) | The total number of records found for the request. |
| links | (object) | An object containing links pertaining to the request itself. |
| self | (url) | The URL of the request. Includes all query parameters. |
Changelog
None (as of 4/3/2020)