Skip to main content

API Request Types

The API platform supports both synchronous and asynchronous requests.

The request type is specified using the "async" query parameter on GET requests: api.finra.org/{resource path}?async=true and as a request parameter on POST requests: "async" : true. 

The async parameter defaults to false if not provided, which indicates a synchronous request.

Synchronous Requests

Synchronous requests (async=false) are RESTful API requests that return a status code and a response body. Once the response body is received, the synchronous operation is complete. A status code of 200 indicates a successful request.

Synchronous requests are best used when the API client is filtering a large dataset to return a limited dataset, or when downloading data within a small time period such as a day. If a synchronous request times out, an asynchronous request should be used.

Asynchronous Requests

Aynchronous requests (async=true) behave differently in that they are a three-legged operation. The first leg of the operation is identical to the request that is made using the synchronous request type except the async  parameter is set to true.

The response to this request includes a status code but DOES NOT include the response body. Instead the response includes a Location header that contains a URL that will be used as the second leg of the operation to check the status of the asynchronous request. Note that the status code will be set to 202 when the initial async request is successful and the Location header has been set to the status URL.

The format of the URL in the Location header is: api.finra.org/async-requests/{resource path}/{request id}.

The API client should invoke the status URL on a recurring basis (polling) until a status code of 200 is received. A status code of 202 will be returned if the asynchronous request is still pending. The recommendation is to poll using the status URL no more than once per minute until a status code of 200 is received.

The response body of the status request will contain the request id parameter (requestId) of the asynchronous operation and a status parameter (status). The status will be set to pending when the status code returned is 202. It will be set to complete when the status code returned is 200.

The response body also contains two additional parameters when the status is complete. The resultLink parameter contains a pre-signed AWS S3 URL that points to the request results (the dataset). The expires parameter will contain an ISSO 9001 UTC time code indicating when the pre-signed resultLink will expire. The API client must invoke the pre-signed URL to obtain the dataset result prior to it expiring, or must restart the asynchronous operation from the beginning. The result will expire 2 hours after a status code of 200 is received from invoking the status URL or 24 hours after the result dataset is created,  whichever is earlier.

IMPORTANT: Do not provide an authorization header when accessing the resultLink URL as it includes an embeded authorization token as a query parameter and the request will return a 400 status code if an authorization header is provided.

 

Asynchronous Request Example

  Action Request Response
1

Submit Async Request

GET: api.finra.org/data/group/firm/name/registeredindividual?async=true

POST: api.finra.org/data/group/firm/name/registeredindividual

{
  "async":true, 

   "limit":100000,

  "offset":200000,
}

StatusCode: 202

Response header "Location" has the status link. 

The response payload is empty.

2 Check status of request

GET:  api.finra.org/async-requests/group/firm/name/registeredindividual/0ba2c6e6-c13b-4a47-989a- c47106ab98ce

StatusCode: 202

{
   "requestId": "0ba2c6e6-c13b-4a47-989a-c47106ab98ce",
   "status": "pending"
}

3 Check status of request

GET: api.finra.org/async-requests/group/firm/name/registeredindividual/0ba2c6e6-c13b-4a47-989a-c47106ab98ce

StatusCode: 200

{
   "requestId": "0ba2c6e6-c13b-4a47-989a-c47106ab98ce",
   "expires": "2020-06-26 19:05:38 UTC",
   "resultLink": {pre-signed S3 URL}
   "status": "complete"
}

Additional Considerations

Platform Usage Limits apply for both synchronous and asynchronous requests. Please review this information in order to design an API integration that is performant and that protects the overall integrity of the API platform.

The response from both synchronous and asynchronous requests include Response Headers that are important when dealing with the platform usage limits. Note that the reponse headers are only included for asynchronous requests when the status is complete (status code 200).