{
  "openapi": "3.1.0",
  "info": {
    "title": "Nexa Business Intelligence — Coverage API",
    "description": "Read-only access to the Nexa AI Lead Finder coverage book: which US states are covered, which government public-records datasets back each state, headline collection totals, and anonymised example openings per state. This API returns only coverage reference data and aggregate, anonymised activity. It never returns business names, street addresses, phone numbers, email addresses, owner names, customer accounts or billing figures.",
    "version": "1.0.0",
    "termsOfService": "https://leads.nexaofs.com/privacy",
    "contact": {
      "name": "Nexa Business Intelligence",
      "url": "https://leads.nexaofs.com/api",
      "email": "support@nexaofs.com"
    },
    "license": {
      "name": "Proprietary — access by issued API key",
      "url": "https://leads.nexaofs.com/privacy"
    },
    "x-privacy-policy": "https://leads.nexaofs.com/privacy"
  },
  "servers": [
    {
      "url": "https://leads.nexaofs.com/api/public/gpt"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/states": {
      "get": {
        "operationId": "listCoveredStates",
        "summary": "List every US state in the coverage book",
        "description": "Returns each covered state with its two-letter code, name, how many public-records sources have been researched, and how many of those already have a built connector.",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Optional filter on state name or two-letter code, e.g. \"TX\" or \"caroli\".",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matching states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "states": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "description": "Two-letter state code."
                          },
                          "name": {
                            "type": "string"
                          },
                          "market": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Internal collection market key when the state maps to one."
                          },
                          "sourceCount": {
                            "type": "integer"
                          },
                          "connectorCount": {
                            "type": "integer",
                            "description": "Sources with a working connector already built."
                          },
                          "methods": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "How records are collected, e.g. \"Socrata\", \"CKAN\", \"ArcGIS\"."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/states/{state}": {
      "get": {
        "operationId": "getStateSources",
        "summary": "Get the public-records sources for one state",
        "description": "Describes each government dataset behind a state: dataset name, geographic coverage, collection method, refresh cadence, usage restrictions, whether a connector is built, and the official page to open.",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "Two-letter state code, e.g. \"PA\" or \"TX\".",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The state's sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "coverage": {
                            "type": "string"
                          },
                          "statewide": {
                            "type": "boolean"
                          },
                          "method": {
                            "type": "string"
                          },
                          "cadence": {
                            "type": "string"
                          },
                          "restrictions": {
                            "type": "string"
                          },
                          "declared": {
                            "type": "string"
                          },
                          "connectorBuilt": {
                            "type": "boolean"
                          },
                          "officialPageUrl": {
                            "type": "string"
                          },
                          "note": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "That state is not in the coverage book."
          }
        }
      }
    },
    "/coverage": {
      "get": {
        "operationId": "getCoverageSummary",
        "summary": "Headline coverage totals",
        "description": "Aggregate figures for the whole programme: states covered, businesses tracked, public-record signals collected, and how many sources are enabled. `countsLive` is false when live totals are temporarily unavailable.",
        "responses": {
          "200": {
            "description": "Headline totals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statesLive": {
                      "type": "integer"
                    },
                    "statesResearched": {
                      "type": "integer"
                    },
                    "businesses": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "permitSignals": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "enabledSources": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "countsLive": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/activity/{state}": {
      "get": {
        "operationId": "getStateActivity",
        "summary": "Anonymised collection activity for one state",
        "description": "How much has been collected for a state, when the newest record landed, and anonymised example openings (city, vertical, opportunity score and signal age only). This API returns only coverage reference data and aggregate, anonymised activity. It never returns business names, street addresses, phone numbers, email addresses, owner names, customer accounts or billing figures.",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "Two-letter state code, e.g. \"PA\" or \"TX\".",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The state's activity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string"
                    },
                    "businesses": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "signals": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "newestRecordAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "ISO timestamp of the newest record on file, or null."
                    },
                    "sourcesReporting": {
                      "type": "integer"
                    },
                    "countsLive": {
                      "type": "boolean"
                    },
                    "examples": {
                      "type": "array",
                      "description": "Anonymised example openings. No name, address or contact is ever included.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "vertical": {
                            "type": "string"
                          },
                          "city": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "state": {
                            "type": "string"
                          },
                          "openingConfidence": {
                            "type": "number"
                          },
                          "opportunityScore": {
                            "type": "number"
                          },
                          "declaredValueTotal": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "daysSinceSignal": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "estimatedOpenDate": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "That state is not in the coverage book."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}