API Documentation

Overview

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

  • GET /api/v1/company/ – Retrieve details for a single company.
  • GET /api/v1/companies/ – Retrieve a list of companies with CH data (supports filters).
  • GET /api/v1/companies-contact/ – Retrieve a paginated list of companies whose contact details have been updated, with filters by SIC code.

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

Endpoint: Single Company

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

Method: GET

Required Query Parameter: company_number

Example:

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

Endpoint: Multiple Companies

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

Method: GET

This endpoint supports these optional parameters:

  • sic_code (string) – One or more comma-separated SIC codes (max 2) to filter companies.
  • updated_from and updated_to (string, YYYY-MM-DD HH:MM:SS) – Updated date range. If updated_to < 2025-03-01, returns records with updated_at IS NULL.
  • incorporation_from and incorporation_to (string, YYYY-MM-DD HH:MM:SS) – Incorporation date range.
  • page (integer) – Page number (default: 1).
  • limit (integer) – Number of records per page (default: 100).

Example:

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"

New Endpoint: Companies Contact

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

Method: GET

Returns companies whose contact details were updated after a given date, filtered by SIC codes and excluding bounced emails.

Required Parameters:

  • sic_codes (string) – One or two comma-separated SIC codes (e.g. 69201,69202).
  • updated_after (string) – Date in YYYY-MM-DD format; only companies with date_last_checked > this date.

Optional Parameters:

  • page (integer) – Page number (default: 1).
  • limit (integer) – Records per page (default: 100).

Example:

curl -X GET "https://buddy.biz/api/v1/companies-contact/?api_key=YOUR_SECURE_API_KEY&sic_codes=69201,69202&updated_after=2025-04-15&page=1&limit=100"

Example Response

{
    "page": 1,
    "perPage": 100,
    "totalCompanies": 42,
    "totalPages": 1,
    "companies": [
        {
            "full_company_number": "01234567",
            "website": "https://example.com",
            "trading_name": "Example Trading",
            "employees": 25,
            "cash_in_bank": 10000,
            "net_assets": 50000,
            "email": "info@example.com",
            "telephone": "01234567890",
            "date_domain_registered": "2018-06-15",
            "http_status": 200,
            "is_holding_page": false,
            "is_relevant_page": true,
            "is_foreign_page": false,
            "linkedin": null,
            "twitter": null,
            "facebook": null,
            "email_status": "exists",
            "date_last_checked": "2025-04-20"
        }
        // … more companies …
    ]
}

Error Handling

Errors return JSON with an error key and appropriate HTTP status:

  • 400 Bad Request – missing/invalid parameters
  • 401 Unauthorized – invalid API key
  • 404 Not Found – no matching records

Request an API Key

If you need an API key to access the endpoints, enter your email below:

Field Definitions

  • full_company_number: Company number (8 digits).
  • website: Company website URL.
  • email: Primary contact email.
  • date_last_checked: When contact details were last verified.
  • email_status: “exists” or “not_exists”.

Additional Notes

This API adheres to RESTful principles and returns JSON. All date formats are ISO 8601.