{
  "openapi": "3.0.3",
  "info": {
    "title": "Public Limited Company API",
    "version": "1.0.0",
    "description": "Every UK public limited company on the Companies House register, with the enrichment held on publiclimitedcompany.co.uk, as JSON. Search is free. A full company or officer record costs one credit (one pound); the same key fetches the same record again free for 12 months. Every field carries its source and date.",
    "contact": { "email": "editor@publiclimitedcompany.co.uk" },
    "license": { "name": "Data: Open Government Licence v3.0, CC0 1.0 and FCA NSM terms, as stated per source in each record" }
  },
  "servers": [{ "url": "https://www.publiclimitedcompany.co.uk/api/v1" }],
  "components": {
    "securitySchemes": { "key": { "type": "http", "scheme": "bearer", "description": "Your API key, sent as Authorization: Bearer <key>" } },
    "schemas": {
      "Field": { "type": "object", "properties": { "value": {}, "source": { "type": "string" }, "as_at": { "type": "string" } } },
      "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } },
      "RecordResponse": { "type": "object", "properties": { "charged": { "type": "boolean" }, "credits_remaining": { "type": "integer" }, "free_refetch_until": { "type": "string", "format": "date" }, "test_mode": { "type": "boolean" }, "record": { "type": "object" } } }
    }
  },
  "paths": {
    "/search": {
      "get": {
        "summary": "Search companies by name or number, and officers by name (free, 30 a minute per IP)",
        "parameters": [{ "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }],
        "responses": { "200": { "description": "Up to 20 companies and 20 officers" }, "400": { "description": "Bad query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited" } }
      }
    },
    "/company/{number}": {
      "get": {
        "summary": "Full company record (one credit, free again for 12 months)",
        "security": [{ "key": [] }],
        "parameters": [{ "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z0-9]{8}$" } }],
        "responses": {
          "200": { "description": "The record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } } },
          "401": { "description": "No or unknown key" }, "402": { "description": "No credits left" }, "404": { "description": "Not on the register we hold" }, "429": { "description": "More than 60 requests a minute" }
        }
      }
    },
    "/officer/{officer_id}": {
      "get": {
        "summary": "Full officer record: PLC appointments with roles and dates, and named officers on the same current boards (one credit, free again for 12 months)",
        "security": [{ "key": [] }],
        "parameters": [{ "name": "officer_id", "in": "path", "required": true, "description": "The Companies House officer id, as in /officers/{id}/appointments", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "The record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } } }, "401": { "description": "No key" }, "402": { "description": "No credits" }, "404": { "description": "Not found" } }
      }
    },
    "/account": {
      "get": { "summary": "Credits left, records unlocked and the last 50 ledger lines", "security": [{ "key": [] }], "responses": { "200": { "description": "Account" }, "401": { "description": "No key" } } }
    }
  }
}
