API Documentation

Overview

This API provides access to comprehensive company data in JSON format. It supports two endpoints:

  • GET /api/v1/companies/ – Retrieve a list of companies (supports filters).
  • GET /api/v1/company/ – Retrieve details for a single company.

All requests must include a valid API key as a query parameter.

Authentication

All requests must include the API key:

?api_key=YOUR_SECURE_API_KEY

Single Company Endpoint

URL: https://buddy.biz/api/v1/company/

HTTP Method: GET

Required Parameter: company_number

Example Request:

curl -X GET "https://buddy.biz/api/v1/company/?api_key=YOUR_SECURE_API_KEY&company_number=12345678"

Multiple Companies Endpoint

URL: https://buddy.biz/api/v1/companies/

HTTP Method: GET

This endpoint supports the following optional query parameters:

  • sic_code (string) – One or more comma‑separated SIC codes to filter companies.
  • updated_from and updated_to (string, format YYYY-MM-DD HH:MM:SS) – Updated date range. If updated_to is before 2025-03-01, the API returns records where updated_at is NULL.
  • incorporation_from and incorporation_to (string, format YYYY-MM-DD HH:MM:SS) – Incorporation date range.
  • page (integer) – Page number for pagination (default: 1).
  • limit (integer) – Number of records per page (default: 100).

Example Request:

curl -X GET "https://buddy.biz/api/v1/companies/?api_key=YOUR_SECURE_API_KEY&sic_code=1234,5678&updated_from=2024-01-01%2000:00:00&updated_to=2025-03-15%2000:00:00&incorporation_from=2010-01-01%2000:00:00&incorporation_to=2020-12-31%2000:00:00&page=1&limit=100"

Example Responses

Single Company Response:

{
	"CompanyName": "Example Ltd",
	"CompanyNumber": "12345678",
	"RegAddress.CareOf": "John Doe",
	// ... other fields ...
	"updated_at": "2025-03-10 12:00:00",
	"officers": [
		{
			"id": "1",
			"company_number": "12345678",
			// ... officer details ...
		}
	]
}

Multiple Companies Response:

{
	"page": 1,
	"perPage": 100,
	"totalCompanies": 250,
	"totalPages": 3,
	"companies": [
		{
			"CompanyName": "Example Ltd",
			"CompanyNumber": "12345678",
			// ... other fields ...
			"updated_at": "2025-03-10 12:00:00"
		}
		// ... more companies
	]
}

Field Definitions

  • CompanyName: Registered name of the company.
  • CompanyNumber: Unique identifier.
  • IncorporationDate: Date of formation.
  • updated_at: Last updated timestamp.
  • officers: Array of officer records (returned for a single company).

Error Handling

Errors are returned as JSON with an error key and appropriate HTTP status codes (e.g. 401 Unauthorized, 400 Bad Request, 404 Not Found).

Request an API Key

If you need an API key to access the endpoint, please enter your email address below and click “Request API Key”.

Additional Notes

This API adheres to RESTful principles.