Resources

API reference

Everything the Credyx dashboard does, your systems can do over REST: search official registries, pull full company records and filed financials, and run asynchronous credit risk assessments. All responses are JSON.

Base URL and authentication

All endpoints live under /api. Authenticate with a bearer token in the Authorization header — create and manage keys under Account → API keys. Endpoints marked plan-gated require the corresponding feature in your subscription plan.

curl https://api.credyx.ai/api/search?country=gb&name=acme \
  -H "Authorization: Bearer $CREDYX_API_KEY"

Caching and freshness

Registry records are cached for 7 days and filings for 30 days; responses carry a cached flag and, where applicable, a last_fetched_at timestamp. Every fetch endpoint accepts force_refresh=true to go straight to the source. Risk assessments are never evicted — they form your audit trail.

Errors

Status	Meaning
400	Invalid identifier or unknown id_type for the country.
401	Missing, expired, or revoked bearer token.
403	Feature not in your plan (e.g. risk_analysis, pdf_extraction). The body includes an upgrade_url.
404	No adapter for the country, or company/job not found.
429	Plan quota exceeded (searches/day, lookups/day, financials/month, risk analyses/month) or rate limit hit.
501	The country adapter cannot return real data yet. Credyx never substitutes mock data — a 501 is the honest answer.

Endpoints

GET/api/countries

List supported countries

Returns every country adapter with its capabilities and status. Static metadata by default (fast); pass probe=true to run live health checks against each registry (~30s).

Query parameters

probe (boolean, default false) — Run live health probes against every adapter instead of returning static metadata.

Example response

{
  "countries": [
    {
      "country_code": "gb",
      "name": "United Kingdom",
      "status": "ok",
      "capabilities": { "search": true, "lookup": true, "financials": true },
      "requires_api_key": true,
      "api_key_present": true,
      "rate_limit_per_minute": 600,
      "notes": null
    }
  ]
}

GET/api/search

Search companies by name

Name search within one country via the national registry adapter. If the adapter has no name search (or returns nothing) and fallback is enabled, results come from GLEIF instead — the source field tells you which. Returns 501 when the adapter is not implemented and the fallback found nothing.

Query parameters

country (string, required) — ISO 3166-1 alpha-2 country code, e.g. gb, us, fr.
name (string, required) — Company name query, minimum 2 characters.
limit (integer, 1–50, default 10) — Maximum number of matches.
fallback (boolean, default true) — Fall back to GLEIF when the national adapter has no name search.

Example response

{
  "country": "GB",
  "query": "acme",
  "source": "adapter",
  "results": [
    {
      "id": "01234567",
      "name": "ACME TRADING LIMITED",
      "country": "GB",
      "identifiers": [
        { "type": "COMPANY_NUMBER", "value": "01234567", "label": null }
      ],
      "address": "1 Poultry, London EC2R 8EJ",
      "status": "active",
      "source_url": "https://find-and-update.company-information.service.gov.uk/company/01234567"
    }
  ]
}

GET/api/search/global

Global search (GLEIF)

Name search across GLEIF's LEI database without a country filter — roughly 2M+ legal entities worldwide. Useful when you don't know where a counterparty is registered.

Query parameters

name (string, required) — Company name query, minimum 2 characters.
limit (integer, 1–50, default 10) — Maximum number of matches.

Example response

{
  "query": "acme",
  "source": "gleif",
  "results": [ /* same CompanyMatch shape as /api/search */ ]
}

GET/api/companies/{country}/{identifier}

Company lookup

Full registry record for one company. Served from the Postgres cache when fresh (7-day TTL); otherwise fetched live from the registry. If the identifier is a 20-character LEI, the lookup is resolved via GLEIF regardless of country.

Query parameters

id_type (string, optional) — Override the identifier type (COMPANY_NUMBER, SIREN, KRS, ICO, CIK, …). Defaults to the adapter's primary identifier.
force_refresh (boolean, default false) — Bypass the cache and fetch from the registry.

Example response

{
  "cached": true,
  "last_fetched_at": "2026-07-18T09:12:44Z",
  "details": {
    "id": "01234567",
    "name": "ACME TRADING LIMITED",
    "country": "GB",
    "legal_form": "ltd",
    "status": "active",
    "incorporation_date": "2004-03-19",
    "registered_address": "1 Poultry, London EC2R 8EJ",
    "sic_codes": ["46190"],
    "identifiers": [
      { "type": "COMPANY_NUMBER", "value": "01234567", "label": null }
    ],
    "directors": [
      { "name": "Jane Doe", "role": "director", "appointed_on": "2019-01-04" }
    ],
    "source_url": "https://find-and-update.company-information.service.gov.uk/company/01234567"
  }
}

GET/api/companies/{country}/{identifier}/financials

Financial filings

Filed balance sheets and annual reports for a company, newest first. Cached for 30 days. With with_text=true, PDF filings are downloaded and their text extracted into structured_data.pdf_text_excerpts (slow; requires a plan with the pdf_extraction feature, otherwise 403).

Query parameters

years (integer, 1–20, default 5) — How many filing years to fetch.
force_refresh (boolean, default false) — Bypass the 30-day filings cache.
with_text (boolean, default false) — Extract text from PDF filings. Plan-gated.

Example response

{
  "country": "GB",
  "company_id": "0d4f6c1e-8f2a-4a51-9c1b-3e7a2f0b9d10",
  "cached": false,
  "filings": [
    {
      "year": 2025,
      "type": "annual_report",
      "period_end": "2025-03-31",
      "currency": "GBP",
      "structured_data": { "total_assets": 1830450, "equity": 612300 },
      "document_url": "https://find-and-update.company-information.service.gov.uk/.../document",
      "document_format": "pdf",
      "source_url": "https://find-and-update.company-information.service.gov.uk/company/01234567/filing-history"
    }
  ]
}

POST/api/companies/{country}/{identifier}/risk-analysis

Start a risk analysis

Kicks off an asynchronous credit risk assessment: filings are loaded (fetched if missing), deterministic ratios are computed in code, sanctions screening runs, and the LLM produces the structured verdict. Returns a job id immediately — poll /api/jobs/{job_id} for the result. Requires a plan with the risk_analysis feature.

Example response

{
  "job_id": "7f2b9c34-51de-4a0f-9e6d-2c8b1a7f4e55",
  "status": "queued"
}

GET/api/jobs/{job_id}

Poll a job

Status of an asynchronous job. status moves through queued → running → done (or error). For risk analysis jobs, result contains the full RiskAssessment once done. Assessments are persisted permanently for audit.

Example response

{
  "job_id": "7f2b9c34-51de-4a0f-9e6d-2c8b1a7f4e55",
  "kind": "risk_analysis",
  "status": "done",
  "result": {
    "score": 71,
    "recommendation": "APPROVE",
    "recommended_credit_limit_eur": 50000,
    "reasoning": "Stable revenue, conservative leverage; monitor the fall in quick ratio.",
    "key_signals": ["current_ratio 1.8", "positive equity trend 3y"],
    "red_flags": [],
    "confidence": 0.82,
    "ratios": [
      { "year": 2025, "current_ratio": 1.8, "debt_to_equity": 0.6, "altman_z": 3.1 }
    ],
    "model_used": "gemini-2.5-pro"
  },
  "error": null
}

POST/api/screen

Sanctions screening

Ad-hoc OpenSanctions screening of a company or person, independent of any lookup. The risk engine also screens automatically on every risk analysis run.

Request body

name (string, required) — Entity name to screen.
country (string, optional) — ISO country code to narrow matching.
identifiers (string[], optional) — Registration numbers, LEIs, tax ids.
schema (string, default "Company") — OpenSanctions schema: Company, Person, …
limit (integer, 1–25, default 5) — Maximum hits returned.

Example response

[
  {
    "entity_id": "NK-4bT...",
    "caption": "ACME HOLDINGS LLC",
    "schema": "Company",
    "score": 0.87,
    "datasets": ["us_ofac_sdn"],
    "topics": ["sanction"]
  }
]

GET/api/healthz

Health check

Liveness probe. No authentication required.

Example response

{ "status": "ok" }

Live interactive OpenAPI docs (Swagger) are served by the API itself at /docs on your API host. Questions or missing endpoints: [email protected].