API BETA
Dashboard Documentation Credits
Documentation

Documentation

Version 1.1.2 BETA

Introduction

The Endole API gives you programmatic access to Endole's commercial database. In this documentation, instructions on how to activate your API application, generate a key, making requests, error handling, rate limiting and more are provided.

The Endole API is RESTful API that provides a simple, easy to use approach for requesting data. For each request, the Endole API returns JSON encoded responses and provides standard HTTP response codes.

Getting Started

You can start integrating corporate data into your app or website as soon as you create an Endole account.

To get started:

  1. First, create a free Endole Account.
  2. Open your API Dashboard and click Make New App to create your Endole API application.
  3. Click View App to obtain your Application Key so that Endole can authenticate your API requests.
  4. Perform a test API request (See Authentication below) to confirm your request was successful.

Authentication

Step 1: API application and your API key
Endole authenticates your API requests using your Application Key provided in your API Dashboard. If you do not include a valid key when making an API request, the request will fail and return an error.

Note: Your Application Key can be found in the Dashboard and is provided when you create an Endole API application.

Step 2: Make a test API request
To check that your integration is working correctly, perform a test API request using your key.

To gain access to the API, you will be required to use Basic Authorisation. Your credentials can be passed as a header or as parameters in a HTTP client. When you pass your credentials in the header, you must Base64-encode them.

Your Credentials
									
										{your_app_id}:{your_app_key}

										# Below is an example credentials, separated with a colon (:)
										21754:gUbHT4ChpjzHSN7L9QYIdoninSoK3dL0

										# Example of above credentials once Base64-encoded
										MjE3NTQ6Z1ViSFQ0Q2hwanpIU043TDlRWUlkb25pblNvSzNkTDA=
									
								

The following is an example of an encoded HTTP Basic Authentication header, using the example credentials provided above:

Authorization: Basic MjE3NTQ6Z1ViSFQ0Q2hwanpIU043TDlRWUlkb25pblNvSzNkTDA=

Using clients such as cURL, credentials are added to the request's Authorisation header for you. You pass your credentials with the -u option, as shown in the following example:

cURL
									
										curl https://api.endole.co.uk/company/00445790 \
										  -u 21754:gUbHT4ChpjzHSN7L9QYIdoninSoK3dL0
									
								

Once you have successfully made an API request, you’re ready to begin integrating company data using the Endole API.

Sandbox

As part of the API, sandbox testing is included for developers to test premium API calls. All sandbox calls are treated as regular calls and will return data in the same format.

Note: Data that’s provided in response to sandbox calls is sample data and any requests will not affect your credits.

Enabling sandbox
Enabling sandbox testing is done by adding "sandbox" to the query parameter of the call you would like to make. After a successful call, sample data will be returned as shown in the following example:

GET /company/{company_number}?sandbox=true
									
										curl https://api.endole.co.uk/company/00445790?sandbox=true \
										  -u 12312:gUbHT4ChpjzHSN7L9QYIdoninSoK3dL0
									
								


Sample Response
									
										{
											"accounts":{
												"accounting_reference_date":{
													"day":"26",
													"month":"2"
												},
												"last_accounts":{
													"made_up_to":"2020",
													"period_end_on":"2019-02-23",
													"period_start_on":"2018-02-25",
													"type":"group"
												},
												"next_accounts":{
													"due_on":"2019-02-04",
													"overdue":"2020-02-04",
													"period_end_on":"2020-02-04",
													"period_start_on":"2020-02-04"
												},
												"next_due":"2020-02-04",
												"next_made_up_to":"2020-02-04",
												"overdue":"2020-02-04"
											},
											"annual_return":{
												"last_made_up_to":"2020-02-04",
												"next_due":"2020-02-04",
												"next_made_up_to":"2020-02-04",
												"overdue":"false"
											},
											"branch_company_details":{
												"business_activity":"Any And All Legal Purposes",
												"parent_company_name":"ENDOLE PARENT CO LTD",
												"parent_company_number":"4717940"
											},
											"can_file":"true",
											"company_name":"ENDOLE SAMPLE COMPANY PLC",
											"company_number":"00445790",
											"company_status":"active",
											"company_status_detail":"active-proposal-to-strike-off",
											"confirmation_statement":{
												"last_made_up_to":"2020-02-04",
												"next_due":"2020-02-04",
												"next_made_up_to":"2020-02-04",
												"overdue":"2020-02-04"
											},
											"date_of_cessation":"2020-02-04",
											"date_of_creation":"1947-11-27",
											"external_registration_number":"4517940",
											"foreign_company_details":{
												"accounting_requirement":{
													"foreign_account_type":"accounting-requirements-of-originating-country-do-not-apply",
													"terms_of_account_publication":"accounting-reference-date-allocated-by-companies-house"
												},
												"accounts":{
													"account_period_from":{
														"day":"02",
														"month":"04"
													},
													"account_period_to":{
														"day":"02",
														"month":"04"
													},
													"must_file_within":{
														"months":"07"
													}
												},
												"business_activity":"Any And All Legal Purposes",
												"company_type":"group",
												"governed_by":"Delaware, Usa",
												"is_a_credit_finance_institution":true,
												"originating_registry":{
													"country":"Delaware Secretary Of State, Corporations Division",
													"name":"UNITED STATES"
												},
												"registration_number":"4517940"
											},
											"has_been_liquidated":"false",
											"is_community_interest_company":"",
											"jurisdiction":"england-wales",
											"links":{
												"self":"\/companies\/00445790"
											},
											"partial_data_available":"",
											"previous_company_names":[
												{
													"name":"ENDOLE HOLDINGS LIMITED",
													"ceased_on":"2006-09-01",
													"effective_from":"1981-04-10"
												}
											],
											"registered_office_address":{
												"address_line_1":"Shire Park",
												"address_line_2":"Kestrel Way",
												"care_of":"C\/O",
												"country":"United Kingdom",
												"locality":"Welwyn Garden City",
												"po_box":"3653",
												"postal_code":"AL7 1GA",
												"premises":"115",
												"region":"London"
											},
											"registered_office_is_in_dispute":"false",
											"sic_codes":[
												"47110",
												"57802",
												"68795",
												"13059"
											],
											"subtype":"private-fund-limited-partnership",
											"type":"plc",
											"undeliverable_registered_office_address":"false"
										}
									
								
[+] See all lines

Errors

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Code Summary
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable (often due to missing a required parameter).
401 - Unauthorized No valid credentials provided.
403 - Forbidden The parameters were valid but the request failed, or the request performed did not have permission.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests The API request limit was exceeded (300 requests within a five-minute window).
500, 502, 503, 504 - Server Errors Something went wrong on our end. You may need to contact us if the error persists.

Security

We have installed security measures to ensure your application's performance and security isn't compromised. These are outlined below:

Rate Limiting (Throttling)

The Endole API applies rate limiting (throttling) to ensure that your application is protected in the instance of erroneous loops or excessive requests in a short time. This also ensures other API users won't be affected whilst utilising the Endole API.

An application can make up to 300 requests within a five-minute window. If this limit is exceeded, a 429 Too Many Requests HTTP status code will be returned for each request made for the remainder of the five-minute window.

Increasing your rate limit
If you have an application that requires a higher rate limit than the default, get in touch with us.

IP Whitelisting

To safeguard your application, Endole API provides IP whitelisting. IP whitelisting is a security feature that allows you to specify one or more IP addresses that are permitted access to your application. A maximum of five IP addresses can be whitelisted per application.

Pricing

Premium information is accessed on a pay-per-call basis with no commitments, termination fees, or preset usage limits.

Note: Some calls may return an empty result due to the data being unavailable. You will not be charged for these calls.

Credits
To get started accessing premium information through the Endole API, credits are first required. You can view existing and purchase more credits by clicking Credits.
Financials
Understand financial activity with 5Y Full Financial Accounts, including Balance Sheets, P&L Statements and more.
£0.70
PER CALL
Credit Checks
Evaluate creditworthiness with Credit Scores, Borrowing Limits, and County Court Judgements.
£1.20
PER CALL
Shareholders
Discover who decision-makers are with Shareholders Names and Percentage Ownership.
£0.60
PER CALL
Group Structures
See how companies are linked with Parent, Sibling, and Child company connections.
£0.60
PER CALL
Contacts
Connect with companies with updated GDPR-friendly Contact information and Director names.
£0.20
PER CALL
Comprehensive
Get full access to all information available on a company spanning from Financials to Contacts.
£3.00
PER CALL

Company Profile

To retrieve the details of a company, begin by supplying its unique company number:

GET /company/{company_number}
									
										curl https://api.endole.co.uk/company/00445790 \
										  -u 12312:gUbHT4ChpjzHSN7L9QYIdoninSoK3dL0
									
								


Sample Response
									
										{
											"accounts":{
												"accounting_reference_date":{
													"day":"26",
													"month":"2"
												},
												"last_accounts":{
													"made_up_to":"2020",
													"period_end_on":"2019-02-23",
													"period_start_on":"2018-02-25",
													"type":"group"
												},
												"next_accounts":{
													"due_on":"2020-02-04",
													"overdue":"false",
													"period_end_on":"2020-02-04",
													"period_start_on":"2020-02-04"
												},
												"next_due":"2020-02-04",
												"next_made_up_to":"2020-02-04",
												"overdue":"false"
											},
											"annual_return":{
												"last_made_up_to":"2020-02-04",
												"next_due":"2020-02-04",
												"next_made_up_to":"2020-02-04",
												"overdue":"false"
											},
											"branch_company_details":{
												"business_activity":"",
												"parent_company_name":"",
												"parent_company_number":""
											},
											"can_file":"true",
											"company_name":"TESCO PLC",
											"company_number":"00445790",
											"company_status":"active",
											"company_status_detail":"",
											"confirmation_statement":{
												"last_made_up_to":"2020-02-04",
												"next_due":"2020-02-04",
												"next_made_up_to":"2020-02-04",
												"overdue":"false"
											},
											"date_of_cessation":"",
											"date_of_creation":"1947-11-27",
											"external_registration_number":"",
											"foreign_company_details":{
												"accounting_requirement":{
													"foreign_account_type":null,
													"terms_of_account_publication":null
												},
												"accounts":{
													"account_period_from":{
														"day":null,
														"month":null
													},
													"account_period_to":{
														"day":null,
														"month":null
													},
													"must_file_within":{
														"months":null
													}
												},
												"business_activity":null,
												"company_type":null,
												"governed_by":null,
												"is_a_credit_finance_institution":null,
												"originating_registry":{
													"country":null,
													"name":null
												},
												"registration_number":null
											},
											"has_been_liquidated":"false",
											"is_community_interest_company":"",
											"jurisdiction":"england-wales",
											"links":{
												"self":"/companies/00445790"
											},
											"partial_data_available":"",
											"previous_company_names":[
												{
													"ceased_on":null,
													"effective_from":null,
													"name":null
												}
											],
											"registered_office_address":{
												"address_line_1":"Tesco House, Shire Park",
												"address_line_2":"Kestrel Way",
												"care_of":"",
												"country":"United Kingdom",
												"locality":"Welwyn Garden City",
												"po_box":"",
												"postal_code":"AL7 1GA",
												"premises":"",
												"region":""
											},
											"registered_office_is_in_dispute":"false",
											"sic_codes":[
												"47110",
												"",
												"",
												""
											],
											"subtype":"",
											"type":"plc",
											"undeliverable_registered_office_address":"false"
										}
									
								
[+] See all lines

Company Financials

Retrieve the financials of a company by supplying its unique company number. Responses return 5 years of full company financials where available (ordered by newest first).

An example response of one year company financials can be seen below:

GET /financials/{company_number}
									
										curl https://api.endole.co.uk/financials/00445790 \
										  -u 12312:gUbHT4ChpjzHSN7L9QYIdoninSoK3dL0
									
								


Sample Response
									
										{
											"period_ended":{
												"date_ended":"201902",
												"no_of_months":"12"
											},
											"overview":{
												"consolidated":"Y",
												"currency":"GBP",
												"no_of_employees":"464505",
												"turnover":"63911000000",
												"total_assets_less_current_liabilities":"28367000000",
												"shareholders_funds":"14858000000"
											},
											"profit_loss":{
												"turnover":{
													"turnover":"63911000000",
													"uk_turnover":"0",
													"export_turnover":"0"
												},
												"cost_of_sales":{
													"cost_of_sales":"-59767000000",
													"operational_expenses":"46000000"
												},
												"gross_profit":"4144000000",
												"other_expenses":"-2010000000",
												"operating_profit":{
													"operating_profit":"2153000000",
													"other_income":"35000000",
													"exceptional_items":"0"
												},
												"profit_before_interest":{
													"profit_before_interest":"2210000000",
													"interest_paid":"-536000000"
												},
												"profit_before_tax":{
													"profit_before_tax":"-354000000",
													"taxation":"-354000000"
												},
												"profit_after_tax":1320000000,
												"extraordinary_items":"0",
												"minority_interests":"2000000",
												"profit_for_period":608000000,
												"dividends":"-357000000",
												"retained_profit":"965000000",
												"discontinued_operation":"0",
												"depreciation":"1125000000",
												"auditors_fee":"8000000"
											},
											"employees_directors":{
												"no_of_employees":"464505",
												"total_remuneration":{
													"total_remuneration":"6447000000",
													"wages_salaries":"6447000000",
													"social_security_costs":"520000000",
													"pension_costs":"410000000"
												},
												"total_directors_pay":"8819000",
												"highest_paid_director":"4600000"
											},
											"balance_sheet":{
												"fixed_assets":{
													"tangible_assets":{
														"tangible_assets":"19023000000",
														"land_building":"16850000000",
														"fixtures_fittings":"0",
														"plant_vehicles":"0",
														"other_fixed":"2173000000"
													},
													"intangible_assets":"6264000000",
													"investments":"11092000000",
													"total_fixed_assets":"36379000000"
												},
												"current_assets":{
													"stock_wip":{
														"stock_wip":"2617000000",
														"stock":"0",
														"wip":"6000000"
													},
													"trade_debtors":"598000000",
													"bank_deposits":"2916000000",
													"other_current_assets":{
														"other_current_assets":"5930000000",
														"group_loans_asset":"170000000",
														"directors_loans_asset":"0",
														"investm_other_current_assets":"607000000"
													},
													"total_current_assets":"12668000000"
												},
												"current_liabilities":{
													"trade_creditors":"-5750000000",
													"short_term_loans_overdrafts":{
														"short_term_loans_overdrafts":"-10451000000",
														"bank_overdrafts":"-387000000",
														"group_loans":"-20000000",
														"director_loans":"0",
														"hire_purchases_lease":"-36000000",
														"hire_purchase":"0",
														"leasing":"-36000000",
														"other_short_term_loans":"-10008000000"
													},
													"total_other_current_liabilities":{
														"total_other_current_liabilities":"-4479000000",
														"corporation_tax":"-325000000",
														"dividends":"-357000000",
														"accruals_def_inc_short_term":"-1230000000",
														"social_securities_vat":"-521000000",
														"other_current_liabilities":"-2403000000"
													},
													"total_current_liabilities":"-20680000000"
												},
												"long_term_liabilities":{
													"long_term_debt":"-8969000000",
													"group_loans":"0",
													"director_loans":"0",
													"hire_purchases_lease":{
														"hire_purchases_lease":"-36000000",
														"hire_purchase":"0",
														"leasing":"-36000000"
													},
													"other_long_term_loans":"-8876000000",
													"total_other_long_term_liab":{
														"total_other_long_term_liab":"-4564000000",
														"accruals_def_income":"0",
														"other_long_term_liab":"-773000000",
														"provisions_for_other_liab":"-983000000",
														"deferred_tax":"-236000000",
														"other_provisions":"-747000000",
														"balance_sheet_minorities":"24000000"
													},
													"total_long_term_liabilities":"-13509000000",
													"total_assets":49047000000,
													"total_liabilities":-34189000000,
													"net_assets":"14858000000",
													"shareholders_equity":"14858000000",
													"net_current_assets_working_capital":"-8012000000",
													"total_assets_less_current_liabilities":"28367000000"
												},
												"capital_reserves":{
													"issued_capital":"490000000",
													"total_reserves":{
														"total_reserves":"14368000000",
														"share_premium_account":"5165000000",
														"revaluation_reserves":"0",
														"profit_account":"5405000000",
														"other_reserves":"3798000000"
													},
													"shareholders_funds":"14858000000"
												},
												"cash_flow":{
													"net_cash_flow_from_operations":"2642000000",
													"net_cash_flow_return_on_invest":"-247000000",
													"taxation":"-370000000",
													"net_cash_flow_from_investing_activ":"-1202000000",
													"capital_expenditure_financ_invest":"0",
													"acquisition_disposal":"0",
													"equity_dividends_paid":"-357000000",
													"management_of_liquid_resources":"0",
													"net_cash_flow_from_financing":"-1624000000",
													"increase_in_cash_equivalents":"-1158000000"
												},
												"ratios_percentages":{
													"gross_profit_margin":6.4840168359124401575854790280573070049285888671875,
													"operating_profit_margin":3.368747164024972651219513863907195627689361572265625,
													"profit_margin_before_tax":2.619267418754204879149938278715126216411590576171875,
													"profit_margin_after_tax":2.06537215815743735447540530003607273101806640625,
													"current_ratio":0.61257253384912957461239102485706098377704620361328125,
													"liquidity_ratio":0.486025145067698283174451034938101656734943389892578125,
													"asset_turnover_ratio":1.303056252166289397109721903689205646514892578125,
													"interest_coverage_ratio":4.01679104477611925716473706415854394435882568359375,
													"return_on_assets":4.389667054050196526304716826416552066802978515625,
													"return_on_net_assets":14.4905101628752195352944909245707094669342041015625,
													"return_on_equity":8.88410284022075558141295914538204669952392578125,
													"return_on_capital_employed":7.5898050551697391341576803824864327907562255859375,
													"debtor_days":3.415210552174116731549702308257110416889190673828125,
													"creditor_days":35.1154550169826080718848970718681812286376953125,
													"gearing_total_liabilities":230.104993942657159777809283696115016937255859375,
													"debt_to_capital_ratio":69.706607947478943287933361716568470001220703125,
													"debt_to_equity_ratio":230.104993942657159777809283696115016937255859375,
													"turnover_per_employee":137589.47697010796400718390941619873046875,
													"profit_per_employee":1308.9202484365077907568775117397308349609375,
													"average_pay_per_employee":16460.5332558314767084084451198577880859375,
													"shareholders_funds_per_employee":31986.73857116715589654631912708282470703125,
													"working_capital_per_employee":-17248.4688001205577165819704532623291015625,
													"total_assets_per_employee":105589.821422804918256588280200958251953125
												}
											}
										}
									
								
[+] See all lines