{"openapi":"3.0.3","info":{"title":"CIPAget","version":"0.1.0","description":"Independent, on-demand API for CIPA public register facts. No official affiliation. Section completeness is explicit. Public PDFs are available through the separate documents endpoint."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"def-0":{"type":"object","required":["key","label","value","displayValue"],"properties":{"key":{"type":"string"},"label":{"type":["null","string"]},"value":{"type":["null","string"]},"displayValue":{"type":"string"},"machineValue":{"type":["null","string","number","boolean"]},"group":{"type":"string"}},"title":"Field"},"def-1":{"type":"object","properties":{"headers":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"Table"},"def-2":{"type":"object","properties":{"title":{"type":["null","string"]},"summary":{"type":"array","items":{"type":"string"}},"group":{"type":["null","string"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/def-0"}},"text":{"type":"string"}},"title":"Record"},"def-3":{"type":"object","properties":{"label":{"type":"string"},"status":{"enum":["available","empty","unavailable","restricted","error"]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/def-0"}},"records":{"type":"array","items":{"$ref":"#/components/schemas/def-2"}},"tables":{"type":"array","items":{"$ref":"#/components/schemas/def-1"}},"text":{"type":"string"},"pagesFetched":{"type":"integer"},"total":{"type":["null","integer"]},"complete":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"filingDetails":{"type":"array","items":{"type":"object","additionalProperties":true}},"ownershipStatements":{"type":"array","items":{"type":"object","additionalProperties":true}}},"title":"Section"},"def-4":{"type":"object","properties":{"uin":{"type":["null","string"]},"name":{"type":"string"},"status":{"type":["null","string"]},"register":{"type":["null","string"]},"entityType":{"type":["null","string"]},"registeredOn":{"type":["null","string"]},"address":{"type":["null","string"]},"previousNames":{"type":"array","items":{"type":"string"}},"previousAddresses":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/def-0"}},"text":{"type":"string"}},"title":"SearchItem"},"def-5":{"type":"object","properties":{"query":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/def-4"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"hasMore":{"type":"boolean"},"total":{"type":["null","integer"]},"retrievedAt":{"type":"string"},"source":{"type":"string"},"sourcePagesFetched":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"}}},"title":"SearchResult"},"def-6":{"type":"object","properties":{"kind":{"enum":["incorporationCertificate","standardExtract"]},"status":{"enum":["available","unavailable","restricted","error"]},"filename":{"type":["null","string"]},"mimeType":{"enum":["application/pdf"]},"encoding":{"enum":["base64"]},"contentBase64":{"type":["null","string"]},"sizeBytes":{"type":["null","integer"]},"sha256":{"type":["null","string"]},"retrievedAt":{"type":["null","string"]},"warnings":{"type":"array","items":{"type":"string"}}},"title":"RegistryDocument"},"def-7":{"type":"object","properties":{"uin":{"type":"string"},"name":{"type":"string"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/def-6"}},"complete":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"retrievedAt":{"type":"string"},"source":{"type":"string"}},"title":"DocumentsResult"},"def-8":{"type":"object","properties":{"uin":{"type":"string"},"name":{"type":"string"},"status":{"type":["null","string"]},"entityType":{"type":["null","string"]},"availableSections":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}}}},"sections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/def-3"}},"complete":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"retrievedAt":{"type":"string"},"source":{"type":"string"}},"title":"EntityResult"},"def-9":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"requestId":{"type":"string"}}}},"title":"Error"}}},"paths":{"/v1/search":{"get":{"summary":"Search the register by name or number","tags":["Registry"],"description":"Finds companies and business names the way the “Name or number” box on CIPA's site does. Each match comes back with its number, status, type, registration date and address. Usually takes 0.4 to 2 seconds. Limits: you can search by name or number only, with no filters for type, status or date. Results come 20, 50 or 100 to a page, up to page 20. total can be null, so use hasMore to page. Business names come back without a number (uin is null), so their details cannot be opened from a search result.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":200},"example":"Choppies","in":"query","name":"q","required":true,"description":"A name or part of one, a company UIN, or a business-name registration number. 2 to 200 characters."},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":1},"in":"query","name":"page","required":false,"description":"Which page of results to return, 1 to 20."},{"schema":{"type":"integer","enum":[20,50,100],"default":20},"in":"query","name":"pageSize","required":false,"description":"Results per page."}],"security":[],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-5"},"meta":{"type":"object","properties":{"cache":{"enum":["hit","miss","coalesced"]},"ageMs":{"type":"number"},"durationMs":{"type":"number"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"504":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}}}}},"/v1/entities/{uin}":{"get":{"summary":"Read one company or business name","tags":["Registry"],"description":"Opens one entity on CIPA's site and reads its tabs: general details, addresses, directors, secretaries, shareholders, share allocations, beneficial owners, auditors, the ownership diagram's data and the list of filings. By default it reads every tab, including previous names, addresses and office holders. A full read takes about 2.5 to 7 seconds; include=general takes about 2. Limits: it needs the exact number, not a name, so search first. Each list is read up to maxPages pages; when a list is longer, complete is false and warnings says which section stopped early. Ownership data covers the entity's direct owners only; related companies are not opened. PDFs are not included here; use /v1/entities/{uin}/documents.","parameters":[{"schema":{"type":"string","default":"all","maxLength":1000},"example":"general,addresses","in":"query","name":"include","required":false,"description":"Section keys separated by commas, or all on its own. Fewer sections means a faster call. Common keys: general, addresses, directors, secretaries, shareholders, shareAllocations, beneficialOwners, auditors, visualisation, filings."},{"schema":{"type":"boolean","default":true},"in":"query","name":"history","required":false,"description":"Also read the “show previous” lists: former directors, old addresses, earlier names and statuses."},{"schema":{"type":"boolean","default":false},"in":"query","name":"filingDetails","required":false,"description":"Also open each filing's own dialog. Much slower."},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":10},"in":"query","name":"maxPages","required":false,"description":"The most pages to read in any one list."},{"schema":{"type":"string","pattern":"^(?:[Bb][Ww][0-9]{5,20}|[Bb][Nn][0-9]{4}/[0-9]{1,10})$"},"example":"BW00000790718","in":"path","name":"uin","required":true,"description":"A company UIN (BW followed by 5 to 20 digits), or a business-name registration number (BN, the year, a slash and a number) with the slash written as %2F."}],"security":[],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-8"},"meta":{"type":"object","properties":{"cache":{"enum":["hit","miss","coalesced"]},"ageMs":{"type":"number"},"durationMs":{"type":"number"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"504":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}}}}},"/v1/entities/{uin}/documents":{"get":{"summary":"Download the certificate and standard extract","tags":["Documents"],"description":"Fetches the two free PDFs CIPA offers for an entity and returns them inside the JSON as base64, each with its filename, size in bytes and a SHA-256 hash. CIPA builds these PDFs on request, so this commonly takes 10 to 20 seconds; the limit is DOCUMENT_TIMEOUT_MS (180 seconds by default). Limits: only these two documents; nothing is bought, emailed or logged in to. Each PDF can be at most 10 MiB. One document request runs at a time. A document CIPA does not offer comes back with status unavailable and no content. The hash describes the bytes returned; it does not check a digital signature.","parameters":[{"schema":"object","in":"query","name":"type"},{"schema":false,"in":"query","name":"additionalProperties"},{"schema":{"type":"string","pattern":"^(?:[Bb][Ww][0-9]{5,20}|[Bb][Nn][0-9]{4}/[0-9]{1,10})$"},"example":"BW00000790718","in":"path","name":"uin","required":true,"description":"A company UIN (BW followed by 5 to 20 digits), or a business-name registration number (BN, the year, a slash and a number) with the slash written as %2F."}],"security":[],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/def-7"},"meta":{"type":"object","properties":{"cache":{"enum":["hit","miss","coalesced"]},"ageMs":{"type":"number"},"durationMs":{"type":"number"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"504":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}}}}}},"tags":[{"name":"Registry","description":"Live lookups on CIPA's public register search. Nothing is fetched until you ask."},{"name":"Documents","description":"The two free PDFs CIPA offers for an entity."}],"externalDocs":{"url":"/docs/","description":"Guide in plain English, with forms that send live requests"}}