Welcome to the Enforcement Reports API Usage Documentation page. The documentation provides information regarding how the API retrieves recall information using the various REST Endpoints for the Enforcement Reports application, called iRES (internet Recall Enterprise System). REST endpoints provide a 'RESTful' web service that generates an action to retrieve or act upon a specific piece of information that resides in a database.
To use the API REST Endpoints, enter the Authorization-User and Authorization-Key by clicking the iRES Button at the top. Please submit authorization key requests using the online ORA Unified Logon application.
Each REST Endpoint is documented below and allows users that have entered the Authorization-User and Authorization-Key on this page to see how the request URL is constructed for each REST Endpoint and what each returns. For information on the definition of each result column, please visit the API definitions. When developing a method to utilize this API not using this page, below are some points that may help explain why results are not being returned as expected:
The API cannot be used with a typical web browser (e.g. cutting and pasting the request URL into the URL bar of the browser). This is because the API request requires the use of the Authorization-User and Authorization-Key headers to be transmitted with the request.
API calls are cached, so when constructing the string for an API call unique signatures should be used (as shown in the request URL examples below using "signature="). For example, if you send a request which results in a 401 message (i.e. you put the wrong Authorization-User and Authorization-Key in) and you try that same request with the same signature it will still return a 401 message even with the right Authorization-User and Authorization-Key information entered. It is recommended that signatures should use a date and time numeric component to make the request unique.
The API server has a specified Access-Control-Allow-Origin and so API calls using some methods may not work. For example, regular JavaScript/JQuery may not work due to web browser security designed to not allow cross-domain calls. This is not an issue when calling the API using server-side code such as Java, PHP, or ColdFusion that make server-level HTTP requests.
It is recommended that API calls use TLS 1.2 to avoid any connection related errors.
For POST endpoints the header Content-Type should have the value application/x-www-form-urlencoded.
For requests for assistance regarding the iRES API, please e-mail ORAAPIRequests@fda.hhs.gov.
Following is an example of the iRES API REST Endpoint. You will need to click on the REST Endpoint title to expand the window.
Upon clicking, the REST Endpoints display the six sections including Implementation Notes, Response Class, Parameters, Response Messages, Request URL, and Response Body.
Implementation Notes - Gives a brief description of what data is accessed and displayed.
Response Class - Indicates the response class description of the API.
Parameters - Allows entering query parameters for the endpoint in the text box.
Response Messages - Is a legend that shows the API return codes and their meaning.
Request URL - Shows the URL of the requested API path.
Response Body - Shows the response of the API request.
Finally, notice the Try it out! button. Once you enter a specific value for the selected REST Endpoint in the Parameters field, click the Try it out! button. The results are displayed in the Response Body window.
