The API only accepts GET requests over HTTPS.
The Beauhurst API requires authentication in the form of an API key. To obtain an API key, please contact your subscription's account manager at Beauhurst. Be sure to keep this key private and secure.
", "version": "beauhurstapi" }, "security": [ { "ApiKey": [] } ], "paths": { "/v1/companies": { "get": { "operationId": "v1_companies_list", "summary": "Returns paginated data on Companies from the Company ID (the Beauhurst ID, not the Companies House ID)", "description": "You must pass the IDs of the companies you want. Use the 'includes' parameter to select which fields you want", "parameters": [ { "name": "sort", "in": "query", "description": "Which field to use when ordering the results.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results.", "required": false, "schema": { "type": "integer" } }, { "name": "company_ids", "in": "query", "required": true, "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 8, "minLength": 6 } } }, { "name": "includes", "in": "query", "required": true, "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "registered_name", "registration_date", "other_trading_names", "companies_house_id", "employee_count_range", "last_modified_date", "beauhurst_url", "website", "tracked_status", "started_tracking_at", "company_status", "is_sme", "cessation_date", "ultimate_parent_company", "sectors", "top_level_sector_groups", "industries", "top_level_industry_groups", "buzzwords", "latest_stage_of_evolution", "stage_of_evolution_transitions", "description", "tracking_reasons", "target_markets", "founder_female_percentage", "sic_codes", "actively_hiring", "legal_form", "signals", "directors", "n_fundraisings", "total_amount_fundraisings", "n_grants", "total_amount_grants", "latest_valuation", "country", "lep", "region", "postcode", "address", "emails", "telephone", "registered_address", "key_contacts", "year_end_date", "turnover", "operating_profit", "ebitda", "total_assets", "number_of_employees", "cash", "total_liabilities", "net_assets", "research_and_development", "export", "auditor", "audit_fees", "trade_creditors", "bank_loans_and_overdrafts", "other_short_term_finance", "twitter_handle", "instagram_handle", "pinterest_handle", "facebook_url", "googleplay_url", "itunes_url", "linkedin_url", "latest_credit_rating", "credit_limit_gbp", "ultimate_parent", "immediate_parent", "all_children", "total_number_of_charges", "number_of_outstanding_charges", "number_of_satisfied_charges" ] } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "required": [ "total", "limit", "offset", "count", "results" ], "type": "object", "properties": { "total": { "description": "Total number of items available.", "type": "integer" }, "limit": { "description": "Number of results to return per page.", "type": "integer" }, "offset": { "description": "The initial index from which to return the results.", "type": "integer" }, "count": { "description": "number of results returned", "type": "integer" }, "results": { "type": "array", "items": { "required": [ "id", "basic", "classification", "corporate_structure", "transactions", "directors", "contact_information", "social_media", "latest_accounts", "historic_accounts", "credit_rating", "charges_and_mortgages" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "minLength": 1 }, "basic": { "required": [ "name", "registered_name", "registration_date", "companies_house_id", "last_modified_date", "tracked_status", "cessation_date" ], "type": "object", "properties": { "name": { "title": "Name", "type": "string", "minLength": 1 }, "registered_name": { "title": "Registered name", "type": "string", "minLength": 1 }, "registration_date": { "title": "Registration date", "type": "string", "format": "date" }, "other_trading_names": { "title": "Other trading names", "type": "string", "readOnly": true }, "companies_house_id": { "title": "Companies house id", "type": "string", "minLength": 1 }, "employee_count_range": { "title": "Employee count range", "type": "string", "minLength": 1 }, "last_modified_date": { "title": "Last modified date", "type": "string", "format": "date-time" }, "beauhurst_url": { "title": "Beauhurst url", "type": "string", "readOnly": true }, "website": { "title": "Website", "type": "string", "format": "uri", "default": "", "minLength": 1 }, "tracked_status": { "title": "Tracked status", "type": "string", "minLength": 1 }, "started_tracking_at": { "title": "Started tracking at", "type": "string", "readOnly": true }, "company_status": { "title": "Company status", "type": "string", "default": "", "minLength": 1 }, "is_sme": { "title": "Is sme", "type": "boolean", "nullable": true }, "cessation_date": { "title": "Cessation date", "type": "string", "format": "date" }, "ultimate_parent_company": { "type": "object", "properties": { "name": { "title": "Name", "type": "string", "default": "", "minLength": 1 }, "companies_house_id": { "title": "Companies house id", "type": "string", "readOnly": true }, "country": { "title": "Country", "type": "string", "default": "", "minLength": 1 } }, "default": { "name": "", "companies_house_id": "", "country": "" } } } }, "classification": { "required": [ "stage_of_evolution_transitions", "description", "sic_codes" ], "type": "object", "properties": { "sectors": { "type": "array", "items": { "type": "string", "nullable": true }, "default": [] }, "top_level_sector_groups": { "type": "array", "items": { "type": "string", "nullable": true }, "default": [] }, "industries": { "type": "array", "items": { "type": "string", "nullable": true }, "default": [] }, "top_level_industry_groups": { "type": "array", "items": { "type": "string", "nullable": true }, "default": [] }, "buzzwords": { "type": "array", "items": { "type": "string", "nullable": true }, "default": [] }, "latest_stage_of_evolution": { "title": "Latest stage of evolution", "type": "string", "minLength": 1 }, "stage_of_evolution_transitions": { "type": "array", "items": { "required": [ "primary_date", "stage_before", "stage_after" ], "type": "object", "properties": { "primary_date": { "title": "Primary date", "type": "string", "format": "date" }, "stage_before": { "title": "Stage before", "type": "string", "minLength": 1 }, "stage_after": { "title": "Stage after", "type": "string", "minLength": 1 } } } }, "description": { "title": "Description", "type": "string", "minLength": 1 }, "tracking_reasons": { "type": "array", "items": { "type": "string", "nullable": true }, "default": [] }, "target_markets": { "type": "array", "items": { "type": "string" }, "readOnly": true, "uniqueItems": true }, "founder_female_percentage": { "title": "Founder female percentage", "type": "number", "format": "decimal" }, "sic_codes": { "type": "array", "items": { "required": [ "code", "description" ], "type": "object", "properties": { "code": { "title": "Code", "type": "string", "maxLength": 5, "minLength": 1 }, "description": { "title": "Description", "type": "string", "maxLength": 256, "minLength": 1 } } } }, "actively_hiring": { "title": "Actively hiring", "type": "string", "minLength": 1 }, "legal_form": { "title": "Legal form", "type": "string", "readOnly": true }, "signals": { "title": "Signals", "type": "string", "readOnly": true } } }, "corporate_structure": { "type": "object", "properties": { "ultimate_parent": { "type": "object", "properties": { "name": { "title": "Name", "type": "string", "default": "", "minLength": 1 }, "companies_house_id": { "title": "Companies house id", "type": "string", "readOnly": true }, "country": { "title": "Country", "type": "string", "default": "", "minLength": 1 } }, "default": { "name": "", "companies_house_id": "", "country": "" } }, "immediate_parent": { "type": "object", "properties": { "name": { "title": "Name", "type": "string", "default": "", "minLength": 1 }, "companies_house_id": { "title": "Companies house id", "type": "string", "readOnly": true }, "country": { "title": "Country", "type": "string", "default": "", "minLength": 1 } }, "default": { "name": "", "companies_house_id": "", "country": "" } }, "all_children": { "type": "array", "items": { "type": "object", "properties": { "name": { "title": "Name", "type": "string", "default": "", "minLength": 1 }, "companies_house_id": { "title": "Companies house id", "type": "string", "readOnly": true }, "country": { "title": "Country", "type": "string", "default": "", "minLength": 1 } }, "default": { "name": "", "companies_house_id": "", "country": "" } }, "default": [] } } }, "transactions": { "type": "object", "properties": { "n_fundraisings": { "title": "N fundraisings", "type": "integer" }, "total_amount_fundraisings": { "title": "Total amount fundraisings", "type": "integer", "minimum": 0 }, "n_grants": { "title": "N grants", "type": "integer" }, "total_amount_grants": { "title": "Total amount grants", "type": "integer" }, "latest_valuation": { "title": "Latest valuation", "type": "integer", "minimum": 0 } } }, "directors": { "type": "array", "items": { "required": [ "name", "email", "from_date", "until_date", "currently_active" ], "type": "object", "properties": { "people_id": { "title": "People id", "type": "string", "minLength": 1 }, "name": { "title": "Name", "type": "string", "minLength": 1 }, "email": { "title": "Email", "type": "string", "minLength": 1 }, "from_date": { "title": "From date", "type": "string", "format": "date" }, "until_date": { "title": "Until date", "type": "string", "format": "date" }, "currently_active": { "title": "Currently active", "type": "boolean" } } } }, "contact_information": { "required": [ "country", "registered_address" ], "type": "object", "properties": { "country": { "title": "Country", "type": "string", "minLength": 1 }, "lep": { "title": "Lep", "type": "string", "minLength": 1 }, "region": { "title": "Region", "type": "string", "minLength": 1 }, "postcode": { "title": "Postcode", "type": "string", "minLength": 1 }, "address": { "title": "Address", "type": "string", "minLength": 1 }, "emails": { "type": "array", "items": { "type": "string", "nullable": true }, "readOnly": true }, "telephone": { "title": "Telephone", "type": "string", "minLength": 1 }, "registered_address": { "type": "array", "items": { "type": "object", "properties": { "address": { "title": "Address", "type": "string", "minLength": 1 }, "county": { "title": "County", "type": "string", "minLength": 1 }, "lep": { "title": "Lep", "type": "string", "minLength": 1 }, "region": { "title": "Region", "type": "string", "minLength": 1 }, "postcode": { "title": "Postcode", "type": "string", "minLength": 1 } } } }, "key_contacts": { "type": "array", "items": { "required": [ "name", "linkedin_url", "currently_active", "title", "is_a_company_founder" ], "type": "object", "properties": { "people_id": { "title": "People id", "type": "string", "minLength": 1 }, "name": { "title": "Name", "type": "string", "minLength": 1 }, "email": { "title": "Email", "type": "string", "default": "", "minLength": 1 }, "beauhurst_url": { "title": "Beauhurst url", "type": "string", "readOnly": true }, "linkedin_url": { "title": "Linkedin url", "type": "string", "format": "uri", "minLength": 1 }, "currently_active": { "title": "Currently active", "type": "boolean" }, "title": { "title": "Title", "type": "string", "minLength": 1 }, "job_functions": { "type": "array", "items": { "type": "string", "nullable": true }, "readOnly": true }, "is_a_company_founder": { "title": "Is a company founder", "type": "boolean" } } }, "readOnly": true } } }, "social_media": { "type": "object", "properties": { "twitter_handle": { "title": "Twitter handle", "type": "string", "minLength": 1 }, "instagram_handle": { "title": "Instagram handle", "type": "string", "minLength": 1 }, "pinterest_handle": { "title": "Pinterest handle", "type": "string", "minLength": 1 }, "facebook_url": { "title": "Facebook url", "type": "string", "format": "uri", "minLength": 1 }, "googleplay_url": { "title": "Googleplay url", "type": "string", "format": "uri", "minLength": 1 }, "itunes_url": { "title": "Itunes url", "type": "string", "format": "uri", "minLength": 1 }, "linkedin_url": { "title": "Linkedin url", "type": "string", "format": "uri", "minLength": 1 } } }, "latest_accounts": { "required": [ "year_end_date" ], "type": "object", "properties": { "year_end_date": { "title": "Date of accounts", "description": "Date P&L Accounts are made up to.", "type": "string", "format": "date" }, "turnover": { "title": "Turnover", "description": "Income earned from normal business activities, net of VAT.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "operating_profit": { "title": "Operating profit", "description": "Earnings from core operations after deducting its operating costs.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "ebitda": { "title": "EBITDA", "description": "Earnings before interest, taxes, depreciation and amortisation.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "total_assets": { "title": "Total assets", "description": "The total of total fixed assets and total current assets.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "number_of_employees": { "title": "Number of employees", "description": "The number of employees in the business.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "cash": { "title": "Cash", "description": "Cash includes cash in hand and cash at bank.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "total_liabilities": { "title": "Total liabilities", "description": "Total debts and financial obligations.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "net_assets": { "title": "Net assets", "description": "Total assets less total liabilities.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "research_and_development": { "title": "R&D expenditure", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "export": { "title": "Export", "description": "Direct exports from the country of incorporation.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "auditor": { "title": "Auditor", "type": "string", "default": "", "minLength": 1 }, "audit_fees": { "title": "Audit fees", "description": "The amount paid to the auditors for the statutory audit.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "trade_creditors": { "title": "Trade creditors", "description": "The amount owing to suppliers for goods and services provided on credit.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "bank_loans_and_overdrafts": { "title": "Bank loans & overdrafts", "description": "Total loans and overdraft obligations due within one year.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "other_short_term_finance": { "title": "Other short term finance", "description": "Any finance to the company due within one year from any organisation other than banks.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true } } }, "historic_accounts": { "type": "array", "items": { "required": [ "year_end_date" ], "type": "object", "properties": { "year_end_date": { "title": "Date of accounts", "description": "Date P&L Accounts are made up to.", "type": "string", "format": "date" }, "turnover": { "title": "Turnover", "description": "Income earned from normal business activities, net of VAT.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "operating_profit": { "title": "Operating profit", "description": "Earnings from core operations after deducting its operating costs.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "ebitda": { "title": "EBITDA", "description": "Earnings before interest, taxes, depreciation and amortisation.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "total_assets": { "title": "Total assets", "description": "The total of total fixed assets and total current assets.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "number_of_employees": { "title": "Number of employees", "description": "The number of employees in the business.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "cash": { "title": "Cash", "description": "Cash includes cash in hand and cash at bank.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "total_liabilities": { "title": "Total liabilities", "description": "Total debts and financial obligations.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "net_assets": { "title": "Net assets", "description": "Total assets less total liabilities.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "research_and_development": { "title": "R&D expenditure", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "export": { "title": "Export", "description": "Direct exports from the country of incorporation.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "auditor": { "title": "Auditor", "type": "string", "default": "", "minLength": 1 }, "audit_fees": { "title": "Audit fees", "description": "The amount paid to the auditors for the statutory audit.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "trade_creditors": { "title": "Trade creditors", "description": "The amount owing to suppliers for goods and services provided on credit.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "bank_loans_and_overdrafts": { "title": "Bank loans & overdrafts", "description": "Total loans and overdraft obligations due within one year.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true }, "other_short_term_finance": { "title": "Other short term finance", "description": "Any finance to the company due within one year from any organisation other than banks.", "type": "integer", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "nullable": true } } } }, "credit_rating": { "required": [ "latest_credit_rating", "credit_limit_gbp" ], "type": "object", "properties": { "latest_credit_rating": { "title": "Latest credit rating", "type": "integer", "nullable": true }, "credit_limit_gbp": { "title": "Credit limit gbp", "type": "integer", "nullable": true } } }, "charges_and_mortgages": { "type": "object", "properties": { "total_number_of_charges": { "title": "Total number of charges", "type": "string", "readOnly": true }, "number_of_outstanding_charges": { "title": "Number of outstanding charges", "type": "string", "readOnly": true }, "number_of_satisfied_charges": { "title": "Number of satisfied charges", "type": "string", "readOnly": true } } } } } } } } } } } }, "tags": [ "v1" ] }, "parameters": [] } }, "servers": [ { "url": "https://platform.beauhurst.com/_api" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "name": "Authorization", "description": "Beauhurst API key", "in": "header" } } } } ```