{"openapi":"3.1.0","info":{"title":"Fylings API","version":"1.0.0","description":"Business verification (KYB) for Africa: search, company records and decision-ready verification verdicts across 1M+ companies and 18 official registries. Every field carries its source, date checked and confidence.","contact":{"email":"hello@fylings.com","url":"https://www.fylings.com/api"}},"servers":[{"url":"https://www.fylings.com/v1"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key, e.g. `Authorization: Bearer fyl_live_…`"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Company":{"type":"object","properties":{"country":{"type":"string","description":"ISO-3166 alpha-2"},"registration_no":{"type":"string"},"legal_name":{"type":"string"},"status":{"type":["string","null"],"enum":["active","dissolved","dormant","unknown",null]},"entity_type":{"type":["string","null"]},"incorporation_date":{"type":["string","null"],"format":"date"},"registered_address":{"type":["string","null"]},"tax_id":{"type":["string","null"]},"source":{"type":"string","description":"The official registry/source of record"},"source_url":{"type":["string","null"]},"last_verified_at":{"type":"string","format":"date-time"},"confidence":{"type":["number","null"],"minimum":0,"maximum":1}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"example":{"error":"invalid_api_key","message":"This API key is not valid or has been revoked."}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Monthly request quota for the key"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left this month"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"When the quota window resets (UTC)"}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"QuotaExceeded":{"description":"Monthly quota exceeded, back off until X-RateLimit-Reset","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/search":{"get":{"operationId":"searchCompanies","summary":"Search companies by name or identifier","description":"Relevance-ranked search. Pagination via limit/offset; `count` in the response is the total matches, so page until offset >= count. Uncached queries may fall through to the live registry (`source: \"live\"`).","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Name, registration number, or tax ID"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Restrict to one ISO country code"},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Matches","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer","description":"Total matches (for pagination)"},"source":{"type":"string","enum":["db","live"]},"checked_registries":{"type":"array","items":{"type":"string"}},"unreachable_registries":{"type":"array","items":{"type":"string"}},"results":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}}}}}},"400":{"description":"Missing ?q=","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/company/{country}/{registration_no}":{"get":{"operationId":"getCompany","summary":"Fetch one full company record","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}},{"name":"registration_no","in":"path","required":true,"schema":{"type":"string"},"description":"Dot- or dash-encoded where applicable (SN.DKR.1974.B.61 or SN-DKR-1974-B-61)"}],"responses":{"200":{"description":"The company record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No such company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/verify":{"get":{"operationId":"verifyBusiness","summary":"Decision-ready KYB verdict","description":"Resolves the business, screens the resolved legal name against OFAC SDN, OFAC Consolidated and UN lists, and returns verified / review / not_found with match confidence, signals and sources.","parameters":[{"name":"name","in":"query","schema":{"type":"string"}},{"name":"registration_no","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Verdict","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"string","enum":["verified","review","not_found"]},"registered":{"type":"boolean"},"match_confidence":{"type":"number"},"company":{"anyOf":[{"$ref":"#/components/schemas/Company"},{"type":"null"}]},"sanctions":{"type":"object"},"data_confidence":{"type":"number"},"signals":{"type":"object"},"sources":{"type":"array","items":{"type":"string"}},"review_reason":{"type":["string","null"]},"checked_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Provide name or registration_no","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}}}}