HTTP API

The API base URL is https://kyc.1above.ai/api/v1. Both operations require an Identity-issued bearer JWT with audience kyc-service, an active operating organization and an explicitly granted corporates:read scope.

Search organizations

curl 'https://kyc.1above.ai/api/v1/organizations/search' \
  --header "Authorization: Bearer $KYC_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"jurisdiction":"HK","query":{"type":"name","value":"EXAMPLE GLOBAL TRADING LIMITED"}}'

Strict matching is the default. For bounded unresolved candidates, put "matching":{"mode":"fuzzy","limit":5} inside the name query. Possible candidates are not established identities and cannot authorize a CDD decision. Selecting a candidate starts a new exact identifier request:

{"jurisdiction":"HK","query":{"type":"business_registration_number","value":"12345678"}}

BRN queries do not accept matching options. HK English names require at least three meaningful word tokens before a legal suffix, while Chinese names require at least two Han characters. China Trading Limited and 中 return 400 validation_error; exact BRNs remain available. A publisher response at its 100-row cap is incomplete and fails closed.

Search results use operation: "search" and distinguish matched, ambiguous, candidates, observed, and not_found. observed establishes an exact identifier through mapping or historical evidence, without claiming a current legal name or standing. Search never delivers addresses. Evidence and freshness describe the observations' authority and temporal coverage.

Get an organization

curl 'https://kyc.1above.ai/api/v1/organizations/HK/12345678' \
  --header "Authorization: Bearer $KYC_ACCESS_TOKEN"

Get accepts an exact normalized BRN and performs no candidate discovery. A caller that already holds the BRN may get directly. Results use operation: "get" with found or not_found; a source failure must not be interpreted as absence.

A found result contains source-faithful facts, evidence, ordered historical name events, source warnings and sourceCoverage (all_configured_sources or partial). Standing is live, not_observed_in_live_datasets, or unknown; absence from live datasets does not mean dissolved. Successful entitled get may deliver the official registered-office or principal-place-of-business address. Get responses use Cache-Control: private, no-store; addresses are excluded from audit records and errors. Audit persistence must succeed before delivery.

Open data does not provide formal Company Particulars Reports, directors, secretaries, members, share capital, charges, filing histories, or document images. KYC does not synthesize these fields or use LTDDIR as a fallback.

Responses and errors

Handled operation responses include X-KYC-Correlation-Id and the same correlationId in JSON. Success is wrapped in result; failure in error with a stable code and sanitized message.

401/403 responses carry a Bearer challenge. Old /organization-identity/lookups and /organization-identity/enrichments routes are removed and return 404. They do not redirect or alias to search/get. Old lookup/enrichment grants do not authorize either current operation; obtain an explicit read grant.