{
  "openapi": "3.1.0",
  "info": {
    "title": "FDA Import Alert Screening",
    "version": "1.0.0",
    "summary": "Screen a firm against every FDA Import Alert Red, Yellow and Green List in one call.",
    "description": "Screen a firm against the Red, Yellow and Green Lists of every published FDA Import Alert in one API call. For import-compliance teams and customs brokers.\n\nGenerated from the service's own TypeScript contract types, so this document describes what the API actually returns. Operated by EAC Ventures, LLC.\n\nSubscribe, including the free tier: https://rapidapi.com/aervik-labs-aervik-labs-default/api/fda-import-alert-red-yellow-green-list-screening-api\n\nKnown limits:\n- Alerts that cover every shipment of a product from a whole country are not assessed, and each response says so.\n- Screening is on the firm name. An FEI number is carried through to the response but not matched, because FDA’s list data has no FEI field to match against.\n- Names are compared after removing punctuation, accents, letter case and common legal forms (such as Ltd, Limited, LLC, S.A.); a name spelled differently in other ways can still score below the match threshold.\n\nSources, freshness and live health: https://aerviklabs.com/sources.json (https://aerviklabs.com/data-sources/#fda-import-alerts). What we do when something cannot be established: https://aerviklabs.com/trust/\n\nThis OpenAPI document is available under the MIT License (Copyright (c) 2026 EAC Ventures, LLC). Use of the API itself is governed by its Terms of Service, not by that license.",
    "contact": {
      "name": "Aervik Labs",
      "url": "https://aerviklabs.com/about/"
    },
    "x-aervik-provenance": {
      "sources_json": "https://aerviklabs.com/sources.json",
      "data_sources_page": "https://aerviklabs.com/data-sources/#fda-import-alerts",
      "trust_page": "https://aerviklabs.com/trust/",
      "read_method": "scheduled-cache",
      "known_limits": [
        "Alerts that cover every shipment of a product from a whole country are not assessed, and each response says so.",
        "Screening is on the firm name. An FEI number is carried through to the response but not matched, because FDA’s list data has no FEI field to match against.",
        "Names are compared after removing punctuation, accents, letter case and common legal forms (such as Ltd, Limited, LLC, S.A.); a name spelled differently in other ways can still score below the match threshold."
      ]
    },
    "termsOfService": "https://fda.aerviklabs.com/terms"
  },
  "externalDocs": {
    "description": "Product page",
    "url": "https://aerviklabs.com/apis/fda-import-alerts/"
  },
  "servers": [
    {
      "url": "https://fda-import-alert-red-yellow-green-list-screening-api.p.rapidapi.com",
      "description": "RapidAPI gateway"
    }
  ],
  "security": [
    {
      "RapidApiKey": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Report the date of the data being served, whether it is stale, and whether its refresh is healthy",
        "parameters": [
          {
            "$ref": "#/components/parameters/RapidApiHost"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/screen": {
      "post": {
        "operationId": "screenFirm",
        "summary": "Screen one firm against the Red, Yellow and Green Lists of every published FDA Import Alert",
        "parameters": [
          {
            "$ref": "#/components/parameters/RapidApiHost"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScreenFirmResponse"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScreenFirmRequest"
              }
            }
          }
        }
      }
    },
    "/screen/batch": {
      "post": {
        "operationId": "screenFirmsBatch",
        "summary": "Screen up to 50 firms in one call, one result per firm in the order supplied",
        "parameters": [
          {
            "$ref": "#/components/parameters/RapidApiHost"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScreenBatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScreenBatchRequest"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "RapidApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Key",
        "description": "Your RapidAPI application key."
      }
    },
    "parameters": {
      "RapidApiHost": {
        "name": "X-RapidAPI-Host",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "const": "fda-import-alert-red-yellow-green-list-screening-api.p.rapidapi.com"
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ],
        "description": "Every non-2xx JSON response from the API itself. `error` is a stable machine-readable code; `message` is for humans and may change. Codes this API can return: `batch_too_large`, `cache_not_provisioned`, `firm_name_too_broad`, `internal_error`, `invalid_fields`, `invalid_json`, `method_not_allowed`, `missing_fields`, `missing_firms`, `not_configured`, `not_found`, `provider_misconfigured`, `refresh_not_configured`, `source_unavailable`, `unauthorized`, `unscreenable_firm_name`. RapidAPI answers authentication, subscription and rate-limit failures itself, in its own format."
      },
      "FdaFirm": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string",
            "description": "The address text FDA printed for this entry. It is not used in screening and the request has no address field: compare it with your supplier's address yourself."
          },
          "country": {
            "type": "string"
          },
          "fei_number": {
            "type": "null",
            "description": "Always null: FDA's published Import Alert list pages carry no FEI number."
          },
          "product_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "product_description": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "date_published": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Date Published FDA prints beside the firm's name in this alert's list, as YYYY-MM-DD when printed as MM/DD/YYYY, otherwise the printed text, or null when none is printed. It is not the alert's own publish date, and the dates FDA prints beside each product are not returned."
          }
        },
        "required": [
          "name",
          "address",
          "country",
          "fei_number",
          "product_code",
          "product_description",
          "notes",
          "date_published"
        ]
      },
      "FdaRunVerdict": {
        "type": "string",
        "enum": [
          "succeeded",
          "failed",
          "skipped_lock_held",
          "in_flight",
          "dead_unrecorded",
          "unknown_status"
        ]
      },
      "FirmMatch": {
        "type": "object",
        "properties": {
          "alert_number": {
            "type": "string"
          },
          "alert_name": {
            "type": "string"
          },
          "list_type": {
            "$ref": "#/components/schemas/ImportAlertListType",
            "description": "Which list of the alert in alert_number this entry appears on. In FDA's words, the Red List is for those that \"have met the criteria for Detention without Physical Examination\", the Yellow List for those \"subject to intensified surveillance\", and the Green List for those that \"have met criteria for exemption\"."
          },
          "matched_name": {
            "type": "string"
          },
          "match_type": {
            "$ref": "#/components/schemas/MatchType",
            "description": "exact: the two names contain the same words once case, punctuation and common company suffixes are normalized. fuzzy: similar, but not the same."
          },
          "score": {
            "type": "number",
            "description": "Deterministic name similarity between the firm_name you sent and matched_name, from 0 to 1, rounded to three decimals."
          },
          "country_match": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the country you sent names this entry's country. null means not comparable (no country sent, or none on FDA's entry), never a mismatch."
          },
          "product_match": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the product you sent shares a word with this entry's product_description. null means not comparable (no product sent, or no description on FDA's entry), never a mismatch."
          },
          "firm": {
            "$ref": "#/components/schemas/FdaFirm",
            "description": "FDA's entry for this firm on the alert in alert_number, as read from that alert's page, so a reviewer can judge the match rather than trust it. When FDA lists more than one product for the firm, product_code, product_description and notes each hold every value joined with \"; \" in page order, so which code goes with which description is not recorded."
          }
        },
        "required": [
          "alert_number",
          "alert_name",
          "list_type",
          "matched_name",
          "match_type",
          "score",
          "country_match",
          "product_match",
          "firm"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded"
            ],
            "description": "ok only when the data is fresh and its refresh is healthy; degraded otherwise, including when a refresh cycle was discarded because an alert page could not be read. The HTTP status is 200 either way."
          },
          "data_as_of": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the refresh cycle behind the served data began reading FDA's pages, or null when that cannot be determined."
          },
          "data_age_days": {
            "type": [
              "number",
              "null"
            ]
          },
          "stale": {
            "type": "boolean",
            "description": "true when the data is older than stale_after_days, or when its age cannot be determined."
          },
          "stale_after_days": {
            "type": "number"
          },
          "last_run_status": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_run_verdict": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FdaRunVerdict"
              },
              {
                "type": "null"
              }
            ]
          },
          "runs_examined": {
            "type": "number"
          },
          "abandoned_in_window": {
            "type": "number"
          },
          "consecutive_ok_cron_runs": {
            "type": "number"
          },
          "degraded": {
            "type": "boolean"
          },
          "degraded_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why refresh health is degraded, or null when it is not. Reported independently of stale."
          },
          "last_refresh_run": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/LastRefreshRun"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "status",
          "data_as_of",
          "data_age_days",
          "stale",
          "stale_after_days",
          "last_run_status",
          "last_run_verdict",
          "runs_examined",
          "abandoned_in_window",
          "consecutive_ok_cron_runs",
          "degraded",
          "degraded_reason",
          "last_refresh_run"
        ]
      },
      "ImportAlertListType": {
        "type": "string",
        "enum": [
          "red",
          "yellow",
          "green"
        ]
      },
      "LastRefreshRun": {
        "type": "object",
        "properties": {
          "trigger": {
            "type": "string"
          },
          "started_at": {
            "type": "string"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "ok",
              "error",
              "skipped",
              "abandoned"
            ]
          },
          "cursor_before": {
            "type": [
              "number",
              "null"
            ]
          },
          "cursor_after": {
            "type": [
              "number",
              "null"
            ]
          },
          "advanced": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the run moved ingest progress forward. null when that cannot be determined, never false by default."
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "trigger",
          "started_at",
          "finished_at",
          "status",
          "cursor_before",
          "cursor_after",
          "advanced",
          "error"
        ]
      },
      "MatchStatus": {
        "type": "string",
        "enum": [
          "match",
          "possible_match",
          "no_match"
        ]
      },
      "MatchType": {
        "type": "string",
        "enum": [
          "exact",
          "fuzzy"
        ]
      },
      "ScreenBatchRequest": {
        "type": "object",
        "properties": {
          "firms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScreenRequest"
            },
            "description": "1 to 50 firms, each the same shape POST /screen accepts. If any firm is invalid, the whole batch is refused with that firm's error."
          }
        },
        "required": [
          "firms"
        ]
      },
      "ScreenBatchResponse": {
        "$ref": "#/components/schemas/ScreenBatchResult"
      },
      "ScreenBatchResult": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScreenResult"
            },
            "description": "One result per firm, in the order supplied."
          }
        },
        "required": [
          "results"
        ]
      },
      "ScreenFirmRequest": {
        "$ref": "#/components/schemas/ScreenRequest"
      },
      "ScreenFirmResponse": {
        "$ref": "#/components/schemas/ScreenResult"
      },
      "ScreenRequest": {
        "type": "object",
        "properties": {
          "firm_name": {
            "type": "string",
            "description": "Required. 1 to 200 characters, with at least one Latin letter or digit; a name with none is refused with unscreenable_firm_name rather than screened."
          },
          "fei_number": {
            "type": "string",
            "description": "Optional. Echoed back in input for your records and never matched: FDA's published Import Alert list data has no FEI field."
          },
          "product": {
            "type": "string",
            "description": "Optional, up to 200 characters. Sets product_match on each match. It never removes a match."
          },
          "country": {
            "type": "string",
            "description": "Optional, up to 200 characters. Sets country_match on each match. It never removes a match."
          }
        },
        "required": [
          "firm_name"
        ]
      },
      "ScreenResult": {
        "type": "object",
        "properties": {
          "input": {
            "$ref": "#/components/schemas/ScreenRequest"
          },
          "status": {
            "$ref": "#/components/schemas/MatchStatus",
            "description": "match or possible_match is a name-similarity classification that needs independent verification. no_match means no entry in the most recent complete refresh of FDA's published lists was similar enough; it is not a clearance."
          },
          "matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FirmMatch"
            }
          },
          "records_below_match_threshold": {
            "type": "number"
          },
          "incomplete_coverage": {
            "type": "boolean",
            "description": "True when this screen is not a complete read. Causes: the Import Alert list was not read live; a record resembling the name was withheld because it may identify an individual (withheld_possible_individual); or firm_name arrived as a single word with no spaces and nothing matched -- see coverage_note. When true, a no_match is not a clean result."
          },
          "withheld_possible_individual": {
            "type": "boolean"
          },
          "coverage_note": {
            "type": [
              "string",
              "null"
            ],
            "description": "One or more sentences explaining why incomplete_coverage is true, or null. It names no individual. The joined-name case reads: FDA Import Alert firm names are usually several words, so a joined or compacted spelling can fail to match the listed record even when the firm is listed, and such a no_match is not sufficient to establish a clean screen -- re-screen the spaced legal or company name."
          },
          "source": {
            "$ref": "#/components/schemas/SourceManifest"
          },
          "disclaimer": {
            "type": "string",
            "description": "Carried in full on every result. It states that Import Alerts covering a product from an entire country are NOT ASSESSED, so a no_match does not rule them out."
          }
        },
        "required": [
          "input",
          "status",
          "matches",
          "records_below_match_threshold",
          "incomplete_coverage",
          "withheld_possible_individual",
          "coverage_note",
          "source",
          "disclaimer"
        ]
      },
      "SourceBasis": {
        "type": "string",
        "enum": [
          "live",
          "mock",
          "mock-pending-ingest"
        ]
      },
      "SourceManifest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "basis": {
            "$ref": "#/components/schemas/SourceBasis",
            "description": "live: screened against data ingested from FDA's published Import Alert pages. mock: screened against a clearly-labeled fixture dataset of invented firms, which says nothing about any real firm. mock-pending-ingest: no complete ingest of FDA data has run yet. Check this before relying on a result."
          },
          "as_of": {
            "type": "string",
            "description": "The date (YYYY-MM-DD) of the data this result was screened against. For live data, the date the refresh cycle that produced it began reading FDA's published pages."
          },
          "note": {
            "type": "string",
            "description": "A plain description of how the served data was produced, including when its refresh cycle began and coverage counts when live."
          }
        },
        "required": [
          "name",
          "url",
          "basis",
          "as_of",
          "note"
        ]
      }
    }
  }
}