Sustema

ENTITY developer reference

ENTITY documentation

Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.

Follow one company reference from input to outcome, then prepare your integration, recovery and operational decisions.

  1. Get started

    Use ENTITY when your application needs to identify a legal entity and inspect the information and evidence associated with it. Start with one company reference and one workflow.

  2. Create and secure your workspace

    Personal free testing is designed to start without a payment card or company registration. Follow email verification and the supported passkey or password-plus-authenticator flow, then accept the applicable account/testing terms.

  3. Make your first request

    For a single company reference, the candidate operation is `resolveReference`: `POST /v1/resolutions`. It returns an identity outcome and essential evidence.

  4. Read the result

    Read three things separately: the business outcome, the information and evidence, and the usage receipt. An HTTP success does not by itself mean the company was identified.

  5. Understand coverage, freshness and reuse

    Check the released capability profile before relying on a territory, identifier, source or information module. A schema that can represent an identifier does not prove that the corresponding source is enabled for your account.

  6. Understand credits and limits

    Use the actual offer and service profile shown for your workspace. There are no confirmed numeric tariffs, free allowances or production limits in this draft.

  7. Recover without duplicating work

    Read the typed error's `code`, `retry_action` and `usage_state`. HTTP status alone is insufficient, especially after an uncertain completion.

  8. Continue into a paid workspace

    When an eligible paid offer is released, review its actual price, allowance, limits, expiry/renewal, taxes and terms before accepting. Workspace membership, technical access and purchasing authority are separate.

  9. Integrate the supported release

    Use the release-matched OpenAPI, field dictionary, error catalogue and binding information together.

  10. Get help or report incorrect information

    For a technical or account issue, use Reports with a safe request/operation reference, the time, the action you attempted and the relevant error.

  11. Before you rely on the result

    Check the intended company, supported scope, evidence, freshness, limitations and applicable reuse rights. Decide how your application handles ambiguity, partial information and unavailable service before automating the workflow.

Access and integration guides

Frequently asked questions

ENTITY is being prepared for release. These answers explain the planned service. Live API access, free testing and developer credentials are not available from these pages.

What problem does ENTITY solve?

When your CRM and onboarding system use different details for the same company, someone has to check that they refer to the same legal entity. External sources can add further differences. ENTITY is being built to give those systems a common company reference, with evidence you can inspect. That can reduce repeated checks and give the workflows using those records a more reliable starting point.

ENTITY is designed to return available corporate relationships and relevant intelligence, with confidence and supporting evidence. What you receive depends on the country, the information available and the services included in your access.

Who is ENTITY for?

ENTITY is for teams whose work depends on knowing which company a record refers to. That includes developers building software or AI workflows, data and platform teams connecting systems, onboarding teams, and people working in insurance, procurement, risk and compliance. You can begin with one workflow where inconsistent company information causes repeated work or uncertainty.

A business user can assess the outcomes and evidence without knowing the API details. A developer will connect ENTITY to the systems where those outcomes are needed. Your organisation keeps control of its business rules and decisions.

We already have identity and access management. Why do we need ENTITY?

Your identity and access management service controls who or what can access a system and what they can do. ENTITY is being built to identify the legally recognised company that a business record, transaction or decision concerns. A user can be correctly signed in while their customer record points to the wrong subsidiary.

National registers are the authoritative source of truth for a company’s registered legal identity. Where released ENTITY coverage is backed by registers, it will link the company to the relevant official record and give your systems a common company reference. Supporting evidence adds available relationships and intelligence. Your existing access controls stay in place, with ENTITY supplying the company context.

We already use company-data providers. Why would we use ENTITY?

Useful company information can come from several sources, while your applications still need to agree on the legal entity to which it belongs. ENTITY is being built to provide a common identity reference and evaluate supporting information field by field. You can retain existing providers and systems rather than rebuilding every workflow around one provider’s identifier.

The relevant national register is the authoritative source for a company’s registered legal identity. Other facts, such as ownership relationships or reported business activity, may require different evidence. Data access and reuse remain subject to the applicable rights and service scope.

Does ENTITY make our onboarding, compliance or underwriting decisions?

No. ENTITY is being built to supply company identity and the available supporting information, confidence and evidence. Your organisation decides whether to onboard a customer, accept a supplier, underwrite a policy or take another business action. Those decisions depend on your rules, obligations and risk appetite.

ENTITY can support a decision process, but a high confidence score is not approval of the company or a guarantee that the decision meets your obligations. Optional intelligence and any formal service commitments are defined separately.

Can we start with one workflow instead of replacing our systems?

Yes. Start where the identity question causes a specific problem, such as creating a company account, matching a supplier or linking records used in portfolio analysis. Once service access is available, your developer can connect that workflow to ENTITY and assess the returned identity, evidence and differences before deciding whether to expand its use.

Agree what improvement would matter for that workflow, such as fewer manual lookups or more consistent company references. ENTITY does not automatically alter your existing records, and savings depend on your data and how you use the results.

Can ENTITY show problems or duplicates in our existing records?

Once service access is available, when different references match the same legal entity, you can use the returned ENTITY identifier to recognise potential duplicate company records in your own systems. You can also compare information you supplied with the returned result to see additional fields, differing values or fresher evidence. Your team decides which changes to apply.

A difference is not automatically an error: a registered office and a trading address may both be correct. Repeated company references may also be legitimate, such as separate policies or transactions. The standard API returns information for your systems to use; it does not merge or rewrite your source records.

Which countries and data sources does ENTITY cover?

Check the released coverage information for the countries, entity types, fields and services available to your account. The initial launch plan uses UK Companies House data and GLEIF information for entities with a Legal Entity Identifier. French register coverage may follow after its separate qualification; it is not required for the first launch.

Access will be enabled only after the relevant sources and usage rights are qualified. These sources provide different kinds of evidence. LEI coverage does not mean every company in a country is included or that every use is permitted. A source named in a plan is not necessarily available in the service. Additional national-register and US discovery coverage require separate qualification and release.

How fresh is the company information?

Freshness depends on the source and the particular field. ENTITY is designed to provide dates and evidence context so you can see how current the information is for your purpose. A recently retrieved record may still describe an older event; a recent update to one field does not make every field current.

Use the relevant observation, effective and review dates together. Unknown freshness is identified rather than replaced with an invented date. Source refresh commitments and any change-notification service are defined in the available service scope.

What does the confidence percentage tell me?

In the planned service, the percentage is designed to show how strongly the available evidence supports the information. The planned response includes an overall score for a defined set of information, then scores for each topic and individual field. Each percentage has a label: Strong support, Supported or Limited support. You will be able to inspect what supports the result, where evidence is missing and where sources disagree.

The assessment is designed to consider the source’s authority for each fact and whether its origin can be traced. It also considers freshness, checks and confirmation from independent sources that meet our evidence rules. Copies of the same source count as one source. A 90% score describes evidence support; it is not a measured 90% probability of correctness. Confidence in matching your request to the right company is assessed separately. Information that cannot be assessed will be labelled Not assessed.

Can you add a country or dataset that my business needs?

You can discuss the country, fields and workflow you need with us. Expansion can use suitable national-register data or licensed datasets, including OpenCorporates. We assess availability, usage rights, quality, refresh requirements and cost before agreeing the scope and timing. Purchasing data does not automatically make every field suitable for release.

Additional countries and specialist datasets are released separately. An expansion request is not a commitment to a delivery date or an automatic data purchase.

Can I explore ENTITY before creating an account?

Yes. You can read the documentation and inspect labelled example requests and responses without an account. Examples help you understand the information ENTITY is designed to return, including confidence and supporting evidence. Live API access and test requests are not yet available.

Example data is clearly distinguished from a live result. Opening or copying an example does not silently run a chargeable request.

Do I need company details or a credit card to try ENTITY?

The planned personal account route uses an email address, email verification, secure sign-in and acceptance of the account terms. Company details and a credit card are not required for that route. Account registration and service access are separate: registering an account does not activate live testing or grant an allowance.

Free testing will have usage and service limits. The applicable offer and allowance must be available before activation; creating another workspace will not create another personal allowance.

What information do I need to send to identify a company?

Start with a valid LEI if you have one. For a registration number, tell us which register issued it, including the country where applicable. Without an identifier, send the company name and country, plus any address or other identifying details you know. Follow the Required fields for your chosen request type. More relevant information can distinguish similar companies and show differences from your records.

Fields marked Required must be completed. Supply other supported fields when you know them. A website domain alone does not identify the legal entity. The API reference lists the accepted fields and validation rules. The Resolve one reference operation and its linked InputReference and Address schemas describe the candidate input fields and constraints. Do not invent missing values; the API reference explains how to handle fields you cannot complete.

Which developer tools and AI integrations are available?

The developer experience is planned around a versioned API description and field dictionary, with Elixir, Python and TypeScript given equal priority for core examples and guidance. An importable API request collection and MCP integration are also planned. Check the released documentation for the tools and versions available to you.

MCP access follows the same permissions, source restrictions and usage controls as the corresponding API operation. Equal language priority does not imply three full SDKs. Use the release-matched guide for your chosen language or agent; a synthetic example is not a published client package.

What happens when ENTITY cannot confidently identify the company?

ENTITY is designed to distinguish an established match from an ambiguous or unsuccessful result. Your application will be able to ask for more identifying information, inspect the permitted explanation or route the case through its own exception process. A similar name or matching web address is not enough to force a legal-entity match.

A strong confidence score for a company record does not resolve ambiguity in your input. Follow the returned outcome and the documented error or next-action guidance. Charge treatment follows the published rule for the operation.

How should my application handle limits, errors and retries?

Use the response status, structured error and request reference described in the API documentation. Rate limits and exhausted credits are different conditions and need different handling. If a response is delayed or its completion is uncertain, follow the operation’s status and retry rules rather than repeatedly submitting new work.

Use the documented idempotency mechanism where supported, retaining the same key for the same logical request. This helps prevent duplicate work or charges. Retry timing, polling limits and completion behaviour are defined per operation.

What uses credits?

In the planned service, credits pay for the outcomes listed in each API operation’s charging rules. Sending a request will not always mean a charge. Some operations will set credits aside before work begins, then confirm the charge once the outcome is known. The usage page is designed to show credits available to spend, reserved for work and already used.

Live API use and charging are not yet available. Before connecting a workflow, check the released pricing and operation documentation for unsuccessful requests, retries and optional intelligence work. Different operations have different charging rules.

What can I do on the free tier?

Free testing is not yet available. Registering an account will not activate an allowance or enable API requests. When service access is ready, the applicable coverage, usage and rate limits will be shown before activation.

Free testing is intended for evaluating the response and integration for your workflow. It will not carry a production service commitment or include every optional service.

What happens if we run out of credits?

Live payments, top-ups, automatic replenishment and plan upgrades are not yet available. Account registration does not enable chargeable work. Once service access is released, new work must remain within the available allowance and the applicable limits.

If you reach a limit, follow the released limit and recovery guidance rather than repeatedly submitting new work. Account information, credential revocation and help will remain subject to their separate access and service limits.

Is industry classification included, and can I choose a standard?

Live industry classification and new on-demand classification research are not yet available. Already-published classifications may be included in future released coverage, with their supporting provenance.

Industry Classification Intelligence remains a separate optional offering. Its supported standards, research, pricing and acceptance conditions require their own released offer.

Do you add the data we submit to a shared company database?

No. The planned standard API uses identifying details to locate the company you mean. They are not automatically treated as evidence for ENTITY’s shared information or contributed to its company database. ENTITY returns information from its governed sources; your organisation remains responsible for its own records.

Request handling and retention are set out in the service and privacy terms. Do not submit unrelated personal, policy, payment or confidential information in company-identity fields. Any separate data-contribution arrangement requires its own terms and controls.

How do API credentials and team access work?

API credentials and company team access are not yet available. Registering an account will not issue an API key or grant developer-service access. Once released, each integration should use a separate, scoped credential with only the access it needs; the secret is designed to be shown once and to support rotation and revocation.

Keep credentials out of source control, browser code and support messages. Being able to develop an integration does not automatically give someone permission to buy services or manage other users.

Where do I get help or discuss an enterprise requirement?

Start with the documentation and FAQs for general questions. For now, use the business enquiry route to discuss a territory, workload, deployment arrangement or purchasing route, and describe what you need to do. Account Reports and a released service-status route will be linked when available. Do not send passwords, tokens or recovery codes in a business enquiry.

Any custom scope, support commitment, marketplace purchase or delivery date needs explicit agreement. Standard API access will not automatically include a custom implementation or a formal service-level commitment.