{
  "openapi": "3.1.0",
  "info": {
    "title": "UK Business Risk + Director Score API",
    "version": "1.0.0",
    "description": "Score any UK company on 0-100 risk plus get director credentials\nand itemised risk factors. Built on Companies House.\n",
    "contact": {
      "name": "Stratum APIs",
      "url": "https://stratumapis.com",
      "email": "support@stratumapis.com"
    },
    "termsOfService": "https://stratumapis.com/legal/terms",
    "x-logo": {
      "url": "https://stratumapis.com/icon.svg",
      "altText": "Stratum APIs"
    }
  },
  "servers": [
    {
      "url": "https://api.stratumapis.com/v1/business-risk",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/score/{number}": {
      "get": {
        "summary": "Risk score + factor breakdown for a single company",
        "description": "Reads the company from Companies House (a company read in the last hour is answered from that read) and scores it 0-100 (higher is safer) with a band A-F. Every point taken off is listed in `factors` with a stable `code`. Counts as one lookup; a `404` (no such company) and a `503` (Companies House could not be read) are not counted.",
        "operationId": "scoreCompany",
        "parameters": [
          {
            "in": "path",
            "name": "number",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "00445790",
            "description": "Companies House number (digits will be left-padded; SC/NI/OC prefixes preserved)"
          }
        ],
        "responses": {
          "200": {
            "description": "Score",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RiskResponse"
                },
                "examples": {
                  "active": {
                    "summary": "An active plc (Tesco PLC)",
                    "value": {
                      "companyNumber": "00445790",
                      "companyName": "TESCO PLC",
                      "score": 92,
                      "band": "A",
                      "factors": [
                        {
                          "code": "high_officer_churn",
                          "label": "High officer churn",
                          "weight": 8,
                          "detail": "63 resigned vs 11 active."
                        }
                      ],
                      "company": {
                        "companyNumber": "00445790",
                        "companyStatus": "active",
                        "type": "plc",
                        "dateOfCreation": "1947-11-27",
                        "hasCharges": false,
                        "accounts": {
                          "nextAccountsDue": "2027-08-26",
                          "overdue": false
                        },
                        "officers": {
                          "activeCount": 11,
                          "resignedCount": 63
                        }
                      },
                      "scoredAt": "2026-10-21T21:00:00.000Z"
                    }
                  },
                  "dissolved": {
                    "summary": "A dissolved company",
                    "value": {
                      "companyNumber": "13571234",
                      "companyName": "BURWARDSLEY LTD",
                      "score": 0,
                      "band": "F",
                      "factors": [
                        {
                          "code": "status_dissolved",
                          "label": "Company is dissolved",
                          "weight": 90,
                          "detail": "Companies House lists this entity as dissolved."
                        },
                        {
                          "code": "no_active_officers",
                          "label": "No active officers",
                          "weight": 25,
                          "detail": "Companies must legally have at least one director."
                        }
                      ],
                      "company": {
                        "companyNumber": "13571234",
                        "companyStatus": "dissolved",
                        "type": "ltd",
                        "dateOfCreation": "2021-08-17"
                      },
                      "scoredAt": "2026-10-21T21:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "No such company"
          },
          "503": {
            "description": "Companies House could not be read just now (error code companies_house_unavailable) or is not configured. Not charged; try again shortly."
          }
        }
      }
    },
    "/bulk": {
      "post": {
        "summary": "Score up to 50 companies in one call",
        "description": "Results come back in the order sent. Each company looked up counts as one lookup, including a number with no company (`found: false`); a company Companies House could not be read for (`found: null`) is not counted.",
        "operationId": "scoreBulk",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "numbers"
                ],
                "properties": {
                  "numbers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 50
                  }
                }
              },
              "example": {
                "numbers": [
                  "00445790",
                  "13571234"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk results, one per number. found is true (scored), false (Companies House has no such company) or null with error companies_house_unavailable (Companies House could not be read for that company; not charged)."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Stratum-Key"
      }
    },
    "schemas": {
      "RiskResponse": {
        "type": "object",
        "properties": {
          "companyNumber": {
            "type": "string"
          },
          "companyName": {
            "type": "string"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Higher is safer (100 = lowest risk)"
          },
          "band": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "E",
              "F"
            ]
          },
          "factors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "weight": {
                  "type": "integer",
                  "description": "Positive = adds risk (lowers score)"
                },
                "detail": {
                  "type": "string"
                }
              }
            }
          },
          "company": {
            "type": "object",
            "additionalProperties": true
          },
          "scoredAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}