OTC Threshold List API

Pursuant to Rule 203(b)(3) of Regulation SHO and FINRA Rule 4320, a participant of a registered clearing agency (i.e., a clearing firm), that has a fail to deliver position at a registered clearing agency (i.e., National Securities Clearing Corporation) in a Threshold Security for 13 consecutive settlement days must immediately close out that fail to deliver position by purchasing shares of like kind and quantity. (Please click the below Information icon for more details about the Threshold Security).

NOTE: If an OTC Threshold list is not available for a certain date, firms must use the prior day’s OTC Threshold list to comply with Rule 203(b)(3) of Regulation SHO or FINRA Rule 4320 until the relevant OTC Threshold list becomes available. Once available, firms must analyze the OTC Threshold list to ensure full compliance with the aforementioned rules. Similarly, if FINRA publishes an updated OTC Threshold list, firms must review the new list to determine whether any additional action must be taken to maintain compliance with the rules. Be aware that in situations where the OTC Threshold list was posted late, or was amended by FINRA on a subsequent date, that list will be reflected in the archives with a date/timestamp that is later than the date contained in the name of the list.

OTC Threshold List API

Name Description Type
tradeDate Trade Date (yyyy-MM-dd) Date
issueSymbolIdentifier Symbol identifier String
issueName Issue Name String
marketClassCode Code indicates whether the issue is OTC Bulletin Board or non-Bulletin Board (OTCBB, OTC) String
thresholdListFlag

Indicates Reported or Non-Reported (R, NR)

  • R indicates RegShoFlag = Y, if not N
  • NR indicates Rule4320 Flag = Y, if not N
String
marketCategoryDescription Describes the code that indicates whether the issue is OTC Bulletin Board (OTBB) or non-Bulletin Board (Other OTC). This column contains data for trade dates from Jan 14 2019 forward. String
regShoThresholdFlag Subject to the requirements of SEC Rule 203 of Regulation SHO where there is an aggregate fail to deliver position for five consecutive settlement days at a registered clearing agency totaling 10,000 shares or more and equal to at least 0.5% of the issuer’s total shares outstanding. When this occurs, the issue becomes subject to mandatory close-out requirements outlined in the SEC's Regulation SHO. This column contains data for trade dates from Jan 14 2019 forward. String
rule4320Flag Subject to the requirements of FINRA Rule 4320 where, for five consecutive settlement days, there are aggregate fails to deliver at a registered clearing agency of 10,000 shares or more and the reported last sale during normal market hours would value the aggregate fail to deliver position at $50,000 or more. When this occurs, the issue becomes subject to mandatory close-out requirements outlined in NASD Rule 3210. This column contains data for trade dates from Jan 14 2019 forward. String

API Status Codes


Lists applicable status codes and what each code represents.

HTTP Status Code

Reason

200 OK
201 Created
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
409 Conflict
415 Unsupported Media Type
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Request Parameters


Explains available API call parameters
Parameter Value/Example Description Applies to Data Type
group otcMarket Name of the group or category of the data. Setting this parameter returns only dataset(s) belonging to that group. All string
name ThresholdList Unique name of the data within the group. Setting this parameter with group returns one unique dataset. Setting this parameter without group can return one or more dataset(s) across group(s). All string
fields "fields" : ["tradeDate"," issueName" ] Comma delimited list of field names to retrieve. Default is all fields. /data  
sortFields "sortFields" : [ "- tradeDate" ] Comma delimited list of field names to sort by. You can prepend a + or - before the field name to specify an ascending or descending sort on that field respectively. /data string
compareFilters "compareFilters" : [ {

 

"fieldName" : "issueSymbolIdentifier",

"fieldValue" : "AAPL",

compareType" : "EQUAL"       } ]

List of value comparison filters POST /data  
dateRangeFilters "dateRangeFilters" : [ {

 

"startDate" : "2017-02-10",

"endDate" : "2017-05-10",

"fieldName" : "tradeDate "       } ]

List of date range filters. POST /data  
domainFilters "domainFilters" : [ {

 

"fieldName" : " marketClassCode",

 "values" : [“OTCBB”, “Other OTC”]     } ]

List of domain filters. POST /data  
offset "offset" : 10 Record number to start with (exclusive). Default is 0. Range of records to be returned is offset record plus limit. If offset is 0 and limit is 20, then records 1 to 20 are returned for a total of 20 records. If offset is 10 and limit is 10, then records 11 to 20 are returned. /data number
limit "limit" : 10 Number of records to return. The default value is 1000. The max value is 100000. To get all records, user can iterate calls increasing the offset value until no more records are returned. /data number
delimiter "delimiter" : "|" Can be used to specify a character delimiter if the Accept header is text/plain. Default value is a comma. Allowed values are pipe, comma, tab, or control A. Reference https://www.w3schools.com/tags/ref_urlencode.asp for encoding standards in URLs. /data  
quoteValues "quoteValues" : false Can be used to specify if values should be quoted if the Accept header is text/plain. /data  

Request Header Parameters


Request and Response headers explains metadata associated with the API
Parameter Value/Example Description Applies to Data Type
Accept text/plain Can be used to specify a format for the data returned.

 

Supports (application/json, text/plain). If the native data format cannot convert between JSON/CSV, then a status code of 400 will be returned.

If an unsupported MIME type is supplied, then a 406 is returned.

/data string
data-api-version              Used to specify version of the API to use.    

Request Headers


Parameter Value/Example Description Applies to Data Type
Content-Type application/json, text/plain Set to match the format of the request unless an error occurred, in which case it will be application/json. /data string
Record-Total   Total records found at the time of request for the given query excluding limit. /data  
Record-Offset   Record offset number. /data  
Record-Limit   Record limit for the query. /data  

Response Headers


Parameter Value/Example Description Applies to Data Type
Content-Type application/json, text/plain Set to match the format of the request unless an error occurred, in which case it will be application/json. /data string
Record-Total   Total records found at the time of request for the given query excluding limit. /data  
Record-Offset   Record offset number. /data  
Record-Limit   Record limit for the query. /data  

GET /metadata/group/otcMarket/name/ThresholdList


Returns the data dictionary in JSON format. It details the name, type and description of each column.

Request URL

https://api.finra.org/metadata/group/OTCMarket/name/THRESHOLDLIST

Request Headers

{
  "Accept": "application/json"
}

Curl Command

curl https://api.finra.org/metadata/group/OTCMarket/name/THRESHOLDLIST

Response Body



{
  "datasetGroup" : "OTCMARKET",
  "datasetName" : "THRESHOLDLIST",
  "partitionFields" : [ "tradeDate" ],
  "fields" : [ {
    "name" : "tradeDate",
    "type" : "Date",
    "format" : "yyyy-MM-dd",
    "description" : "Trade Date"
  }, {
    "name" : "issueSymbolIdentifier",
    "type" : "String",
    "description" : "Issue Symbol identifier"
  }, {
    "name" : "issueName",
    "type" : "String",
    "description" : "Issue Name"
  }, {
    "name" : "marketClassCode",
    "type" : "String",
    "description" : "Indicates whether the issue is OTC Bulletin Board (U) or non-Bulletin Board (u)"
  }, {
    "name" : "thresholdListFlag",
    "type" : "String",
    "description" : "Indicates  whether the issue is a threshold security pursuant to Regulation SHO (R) or FINRA Rule 4320 (NR)."
  }, {
    "name" : "marketCategoryDescription",
    "type" : "String",
    "description" : "Describes the code that indicates whether the issue is OTC Bulletin Board (U) or non-Bulletin Board (u)"
  }, {
    "name" : "regShoThresholdFlag",
    "type" : "String",
    "description" : "Subject to the requirements of SEC Rule 203 of Regulation SHO  where there is an aggregate fail to deliver position for five consecutive settlement days at a registered clearing agency totaling 10,000 shares or more and equal to at least 0.5% of the issuer’s total shares outstanding. When this occurs, the issue becomes subject to mandatory close-out requirements outlined in the SEC's Regulation SHO"
  }, {
    "name" : "rule4320Flag",
    "type" : "String",
    "description" : "Subject to the requirements of FINRA Rule 4320 where, for five consecutive settlement days, there are aggregate fails to deliver at a registered clearing agency of 10,000 shares or more and the reported last sale during normal market hours would value the aggregate fail to deliver position at $50,000 or more. When this occurs, the issue becomes subject to mandatory close-out requirements outlined in NASD Rule 3210"
  } ]
}





Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 18:48:57 GMT
Content-Type: application/json
Content-Length: 965
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
data-api-version: 1
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

GET /partitions/group/otcMarket/name/ThresholdList


Returns a list of available primary partitions, and sub partitions if applicable. It also returns a list of partition fields. Primary partitions are generally by date.

Request URL

https://api.finra.org/partitions/group/OTCMarket/name/THRESHOLDLIST

Request Headers

{
  "Accept": "application/json"
}

Curl Command

curl https://api.finra.org/partitions/group/OTCMarket/name/THRESHOLDLIST

Response Body

{
"datasetGroup":"OTCMarket",
"datasetName":"THRESHOLDLIST",
"partitionFields":["tradeDate"],
"availablePartitions":
    [
        {"partitions":["2018-07-02"]},
        {"partitions":["2018-06-29"]},
        {"partitions":["2018-06-28"]}
    ]
}

Response Headers

HTTP/1.1 200
Date: Wed, 19 Sep 2018 18:06:42 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 204
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

GET /data/group/otcMarket/name/ThresholdList


Returns data for the specified dataset with basic selection criteria. All data is returned synchronously in the HTTPS response stream.

Request URL

https://api.finra.org/data/group/otcMarket/name/ThresholdList

Request Headers

{
    "Accept": "application/json"
}

Curl Command

curl -X GET --header 'Accept: application/json' 
https://api.finra.org/data/group/otcMarket/name/ThresholdList

Response Body

[{
        "regShoThresholdFlag": "N",
        "issueSymbolIdentifier": "AACAY",
        "issueName": "AAC Technologies Holdings Inc Unsponsored ADR (Cayman Islands)",
        "thresholdListFlag": "NR",
        "marketCategoryDescription": "Other OTC",
        "rule4320Flag": "Y",
        "tradeDate": "2019-01-14",
        "marketClassCode": "OTC"
}] 



Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 19:08:56 GMT
Content-Type: text/plain
Content-Length: 212
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
data-api-version: 1
Expires: 0
Pragma: no-cache
Record-Limit: 1
Record-Offset: 0
Record-Total: 182
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DEN
X-XSS-Protection: 1; mode=block

POST /data/group/otcMarket/name/ThresholdList


Returns data for the specified dataset with advanced selection criteria including value comparison and date range filters. All data is returned synchronously in the HTTPS response stream.

Request URL

https://api.finra.org/data/group/otcMarket/name/ThresholdList

Request Headers

{
    "Accept": "application/json"
}

Filters

Contents of compareFilter.json

{
    "compareFilters": 
    [{ 
        "compareType": "EQUAL", 
        "fieldName": "tradeDate", 
        "fieldValue": "2019-01-14"  
    }] ,
    "limit":1
}

Curl Command

curl -L -d "@compareFilter.json" -H "Content-Type: application/json" 
-X POST https://api.finra.org/data/group/otcMarket/name/ThresholdList

Response Body


[{
        "regShoThresholdFlag": "N",
        "issueSymbolIdentifier": "AACAY",
        "issueName": "AAC Technologies Holdings Inc Unsponsored ADR (Cayman Islands)",
        "thresholdListFlag": "NR",
        "marketCategoryDescription": "Other OTC",
        "rule4320Flag": "Y",
        "tradeDate": "2019-01-14",
        "marketClassCode": "OTC"
}] 



Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 19:08:56 GMT
Content-Type: text/plain
Content-Length: 212
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
data-api-version: 1
Expires: 0
Pragma: no-cache
Record-Limit: 1
Record-Offset: 0
Record-Total: 182
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Get /versions


Returns API version information. All responses are returned in JSON format with the Content-Type response header set to application/json.

Name

Description

version Number denoting the version number
revisions List of revisions from last version.
datePublished Date this version was published.

Request URL

https://api.finra.org/versions

Request Headers

{
   "Accept": "application/json"
}

Curl Command

curl https://api.finra.org/versions

Response Body

[ {
  "version" : "1",
  "revisions" : "initial version",
  "datePublished" : "2018-09-18"
} ]

Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 18:56:02 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 94
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block