Check a business identifier against the registers

Reads a business identifier against the registers this server holds: a Legal Entity Identifier against the GLEIF Level 1 golden copy, or a UK company number against the Companies House free company data product. Both are bulk files synced locally, so no third party sits in the request path and nothing about the lookup leaves the server.

Send identifier with a type of lei or company_number. A company number needs the country whose register it belongs to, because company numbers are only unique inside their own register; GB is the register installed today. A LEI needs no country: the identifier is global by construction. A UK company number is zero-padded to eight characters before it is looked up, so 1234567 and 01234567 are the same company.

The answer gives the entity's legal name, whether it is still live (status, with the register's own wording in status_detail), the country and jurisdiction it was formed in, its category and legal form, and when it was registered. For a LEI it adds checksum_valid — the ISO 7064 MOD 97-10 check digit defined by ISO 17442, which catches a mistyped identifier and says nothing about whether it was ever issued — plus registration_status and next_renewal_at, because a LEI registration can lapse while the entity behind it is perfectly alive.

Where a LEI names its entry in a national register this server also holds, the two records are compared field by field. agreements quotes both sides of each comparison and flags names what differs: name_differs_across_registers, status_differs_across_registers, dissolved_in_national_register, lei_registration_not_current. Names are compared on their letters and digits with the company-form words removed, so only a real difference is reported. Where there is no counterpart, agreements is empty — an absent register is not a disagreement.

sources names every register behind the answer with the date of the copy. That matters here: the Companies House snapshot is republished monthly and can be up to five weeks behind the live register, while the GLEIF golden copy is published daily.

The product answers about organisations, not people. No registered address is stored or returned. A registered address is very often somebody's home, and an identifier alone does not say whether a company or a sole trader stands behind it, so the product holds none of them rather than some of them badly.

curl -X POST https://spaw.co/api/v1/entity \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "213800QILIUD4ROSUO03",
  "type": "lei"
}'

const response = await fetch('https://spaw.co/api/v1/entity', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "identifier": "213800QILIUD4ROSUO03",
    "type": "lei"
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/entity',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'identifier': '213800QILIUD4ROSUO03',
        'type': 'lei'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/entity');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'identifier' => '213800QILIUD4ROSUO03',
        'type' => 'lei'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.verify_entity('213800QILIUD4ROSUO03', type='lei')

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.verifyEntity('213800QILIUD4ROSUO03', {
    type: 'lei'
});

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->verifyEntity('213800QILIUD4ROSUO03', type: 'lei');

{
    "success": true,
    "data": {
        "identifier": "213800QILIUD4ROSUO03",
        "identifier_type": "lei",
        "found": true,
        "reason": null,
        "name": "ACME HOLDINGS LIMITED",
        "status": "active",
        "status_detail": "ACTIVE",
        "country": "GB",
        "jurisdiction": "GB",
        "category": "GENERAL",
        "legal_form": "H0PO",
        "registered_at": "2016-04-21",
        "record_updated_at": "2026-08-14",
        "checksum_valid": true,
        "registration_status": "ISSUED",
        "next_renewal_at": "2027-04-21",
        "other_register": "uk-companies-house",
        "other_identifier": "01234567",
        "flags": [],
        "agreements": [
            {
                "field": "name",
                "lei": "ACME HOLDINGS LIMITED",
                "national_register": "ACME HOLDINGS LIMITED",
                "result": "agree"
            },
            {
                "field": "status",
                "lei": "active",
                "national_register": "active",
                "result": "agree"
            }
        ],
        "sources": [
            {
                "dataset": "gleif-lei-level-1",
                "version": "2026-09-08"
            },
            {
                "dataset": "uk-companies-house-entities",
                "version": "2026-09-01"
            }
        ]
    },
    "meta": {
        "credits_used": 1,
        "credits_remaining": 999,
        "cache_hit": false,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}