AlertFlag API Reference

Company profiles, financial data, credit limits, officers, search, monitoring and alerts for UK companies, over a REST API that returns JSON.

API access is included in the Professional and Enterprise plans. You create and manage your key in the console, under API Access.

Give your agent this link. It is this whole reference as plain text, and needs no login:

For tools that import an API description, use the OpenAPI file:

Neither link contains your key. Give the agent the key as an ALERTFLAG_API_KEY environment variable or through its secrets setting, not in the chat.

Base URL

Authentication

Send your API key in a request header, over HTTPS:

X-API-Key: YOUR_API_KEY

Or as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Example Request

curl https://console.alertflag.com/api/v1/company/00000000 \
     -H "X-API-Key: $ALERTFLAG_API_KEY"

Keeping your key safe

• Call the API from your server. A key placed in a web page or mobile app can be read by anyone.
• Keep the key in an environment variable or secrets manager, not in source code.
• Send it in a header. The api_key URL parameter still works for older integrations but is deprecated, because URLs end up in logs.
• Rotate the key if a team member leaves or you think it has been exposed.

Company numbers are 8 characters, for example 00445790 or SC123456. Shorter all-digit numbers are zero-padded for you.

Monitoring and alerts use the same list as the Monitored Companies page, so a company added through the API appears in the console and is checked in the daily run. To collect new alerts, keep the highest id you have seen and pass it as after_id on the next call.

Company Profile

{
    "success": true,
    "message": "Company profile retrieved successfully",
    "data": {
        "company_number": "00000000",
        "company_name": "EXAMPLE LIMITED",
        "company_status": "active",
        "date_of_creation": "2020-01-01",
        "type": "ltd",
        "registered_office_address": {
            "address_line_1": "123 Example Street",
            "locality": "London",
            "postal_code": "SW1A 1AA",
            "country": "United Kingdom"
        },
        "sic_codes": ["62012"],
        "is_active": true
    },
    "timestamp": "2026-11-10 12:00:00"
}

Financial Data

{
    "success": true,
    "message": "Financial data retrieved successfully",
    "data": {
        "summary": {
            "latest_year": "2025",
            "revenue": 1500000,
            "profit_before_tax": 250000,
            "total_assets": 2000000,
            "shareholders_funds": 1200000,
            "current_ratio": 1.8
        },
        "yearly": {
            "2025": {
                "financial_metrics": {
                    "revenue": 1500000,
                    "profit_before_tax": 250000,
                    "total_assets": 2000000,
                    "current_assets": 800000,
                    "current_liabilities": 444444,
                    "shareholders_funds": 1200000
                }
            }
        }
    },
    "timestamp": "2026-11-10 12:00:00"
}

Credit Limit

{
    "success": true,
    "message": "Credit limit calculated successfully",
    "data": {
        "credit_limit": 42000,
        "formatted_limit": "£42,000",
        "assessment": "Medium Credit Capacity",
        "calculation_date": "2026-11-10",
        "basis": "model",
        "capped": false,
        "parent_company": null,
        "warning": null,
        "note": null,
        "factors_considered": {
            "net_worth": 400000,
            "total_assets": 900000,
            "current_ratio": 1.6
        }
    },
    "timestamp": "2026-11-10 12:00:00"
}

basis says how the figure was reached: model (our AI model on digitally filed accounts), accounts_estimate (accounts not filed digitally), parent_company (supported by a parent, named in parent_company) or base (no accounts filed yet, £500). capped is true at the £50M ceiling. warning carries any overdue-filing or strike-off caution shown in the console. Dormant and non-trading companies answer not_scored.

Start Monitoring a Company

curl -X POST https://console.alertflag.com/api/v1/monitoring \
     -H "X-API-Key: $ALERTFLAG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"company_number": "00000000", "notes": "Key supplier"}'

{
    "success": true,
    "message": "Company added to monitoring",
    "data": {
        "company_number": "00000000",
        "company_name": "EXAMPLE LIMITED",
        "already_monitored": false
    },
    "timestamp": "2026-11-10 12:00:00"
}

Alerts

{
    "success": true,
    "message": "Alerts retrieved successfully",
    "data": {
        "total_results": 1,
        "limit": 50,
        "offset": 0,
        "alerts": [
            {
                "id": 1042,
                "company_number": "00000000",
                "company_name": "EXAMPLE LIMITED",
                "type": "charge",
                "message": "New charge registered",
                "data": null,
                "read": false,
                "created_at": "2026-11-10 06:15:00"
            }
        ]
    },
    "timestamp": "2026-11-10 12:00:00"
}

Usage

{
    "success": true,
    "message": "Usage retrieved successfully",
    "data": {
        "plan": "Professional",
        "daily_requests": 100,
        "requests_today": 12,
        "requests_remaining": 88,
        "resets_at": "2026-11-11 00:00:00"
    },
    "timestamp": "2026-11-10 12:00:00"
}

Error Response

{
    "success": false,
    "message": "Company not found",
    "code": "not_found",
    "request_id": "9f2c1a7b4e6d8035",
    "timestamp": "2026-11-10 12:00:00"
}

Check the HTTP status first, then code for the exact reason. Every response carries an X-Request-Id header; quote it if you contact support.

API rate limits are based on your subscription plan:

• Professional Plan: 100 requests per day
• Enterprise Plan: 1,000 requests per day

The allowance is per account and resets at midnight UK time. Rate limit information is included in the response headers (X-RateLimit-Reset is a Unix timestamp):

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 50
X-RateLimit-Reset: 1794355200

Once the allowance is used the API answers 429 with a Retry-After header. /usage and /info are free to call at any time.

Each example reads the key from an ALERTFLAG_API_KEY environment variable.

• cURL
• PHP
• Python
• Node.js

curl https://console.alertflag.com/api/v1/company/00000000 \
     -H "X-API-Key: $ALERTFLAG_API_KEY"

<?php
$apiKey = getenv('ALERTFLAG_API_KEY');
$companyNumber = '00000000';

$ch = curl_init("https://console.alertflag.com/api/v1/company/{$companyNumber}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => ["X-API-Key: {$apiKey}"],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($status === 200 && !empty($result['success'])) {
    print_r($result['data']);
} else {
    echo "Error {$status}: " . ($result['message'] ?? 'no response');
}

import os
import requests

api_key = os.environ['ALERTFLAG_API_KEY']
company_number = '00000000'

response = requests.get(
    f'https://console.alertflag.com/api/v1/company/{company_number}',
    headers={'X-API-Key': api_key},
    timeout=30,
)

result = response.json()

if response.ok and result.get('success'):
    print(result['data'])
else:
    print(f"Error {response.status_code}: {result.get('message')}")

// Node.js 18+ (server side: do not put your key in browser code)
const apiKey = process.env.ALERTFLAG_API_KEY;
const companyNumber = '00000000';

const response = await fetch(`https://console.alertflag.com/api/v1/company/${companyNumber}`, {
    headers: { 'X-API-Key': apiKey },
});

const result = await response.json();

if (response.ok && result.success) {
    console.log(result.data);
} else {
    console.error(`Error ${response.status}: ${result.message}`);
}