Moody's EVA party provider

Version 1

🎯 Functional documentation

This provider enriches parties of type COMPANY from the Moody's EVA (Entity Verification & Analytics) v2 API. It can be used to enrich

• company party data: name, company number, VAT, LEI, legal form, registered address, NACE 2.1 code, contact info, incorporation date and status
• related parties: shareholders, subsidiaries, branches and officers, as configured
• UBO data: the beneficial-owner buckets listed in uboRelationTypes

Each enabled module is charged as a separate Moody's lookup, so enabling all three multiplies the cost of importing one party. A party for which Harmoney does not yet hold a Moody's identifier costs an extra lookup to find it first.

Supported party types

• COMPANY

Applicable modules

• FINANCIAL_SP_PARTIES
• PARTY_RELATED_PARTIES
• UBO

The APPLICABLE_MODULES setting overrides the provider's own default, so a module that is not listed stays disabled.

Supported countries

Set by the SUPPORTED_COUNTRIES setting — Moody's EVA itself has worldwide coverage.

Relationship buckets

Every Moody's bucket has its own relation-type setting. The value is the Harmoney relation-type code given to each entry in that bucket; leaving it blank skips the bucket. A bucket whose relation type is listed in uboRelationTypes is imported as a UBO, every other configured bucket as a related party.

Moody's bucket	Setting	Default
shareholders	relationTypeShareholder	SHAREHOLDER (related party)
calculatedBeneficialOwners2525	relationTypeBeneficialOwner2525	BENEFICIAL_OWNER_25_DIRECT (UBO)
calculatedBeneficialOwners1050	relationTypeBeneficialOwner1050	off
calculatedBeneficialOwners1010	relationTypeBeneficialOwner1010	off
globalUltimateOwners50	relationTypeGlobalUltimateOwner	off
domesticUltimateOwners	relationTypeDomesticUltimateOwner	off
subsidiariesFirstLevel	relationTypeSubsidiary	off
branches	relationTypeBranch	off
individualData.currentOfficers (corporate)	relationTypeDirector	off
individualData.currentOfficers (natural person)	relationTypeDirectorManager	off

Entries are de-duplicated on their Moody's identifier, so a person published in several buckets yields one UBO and an entity reached through two buckets yields one associated party carrying one relation per bucket.

:::warning relationTypeSubsidiary Large groups return hundreds of first-level subsidiaries, which trips maxAssociatedPartiesCount and fails the whole import. Raise the cap deliberately, or leave the bucket off. :::

Partially failed responses

Moody's consults several data sources per lookup and can report that one of them dropped out while the others delivered. The provider keeps whatever did come back rather than failing the import, and logs a warning naming the source that was missing — that warning is what explains why individual data points are empty.

Input data points

Companies can be searched by name or company number, in addition to the country. The main party is identified by its EVA entityId: when metadataKeyForExternalRefIdentifier is set, the entityId is stored under that metadata key, otherwise it goes to the party's external reference field prefixed MOODY#.

Associated parties and UBOs are keyed on the Moody's BvD id instead and always carry externalIdentifier = MOODY_BVD#<bvdIdNumber>, so each one stays distinct.

How the entityId of an existing party is resolved

When Harmoney re-reads a party it already holds — including dossiers created over the gateway API — the entityId is resolved from three sources, in decreasing order of trustworthiness:

1. the configured metadata key, read from the party's external metadata first and its own metadata second;
2. an external party reference carrying the MOODY# prefix, which proves the provider stored it itself;
3. a best-effort search on the company number, then the VAT number, then the company name — each step running only when the previous one found nothing.

The search resolves a party only when it yields exactly one distinct entityId; several matches are left to manual selection. A failing search degrades to the next source instead of aborting the flow, and every unresolved case is logged with the criteria that were tried. A MOODY_BVD# value is never accepted, so an imported associated party can only be resolved by the search.

⚙️ Configuration

Required authorization settings

• API_KEY: the EVA API key
• resourceUri: https://api.kyc.moodys.com

Moody's publishes no separate sandbox URL — staging and production share the same host, only the key differs.

Implementation class

MoodysV1PartyProvider

Testing with a mocked provider

Set the provider state to MOCKED and leave MOCKED_RESPONSE empty. The provider ships a complete example response and synthesises a matching search hit, so a mocked search and import both work without an API key.

:::warning Writing your own MOCKED_RESPONSE Only do this if you need data the bundled response does not contain, and copy the bundled response as your starting point.

The country code in the mocked response must be a valid ISO 3166-1 alpha-2 code. The United Kingdom is GB, not UK — an invalid code is passed straight through to the party and the import fails with party.company.establishmentCountryCode is not a valid country code. :::

Settings

Settings Configuration

Examples