4. /party-entities

Purpose

Party Entities API can be used by client implementations to query the industry reference data for retrieving additional details of the parties involved on the payment. The details returned include other identifiers the party is known by, name and address details.

The details retrieved through /party-entities API can be used by client implementations for payment enrichment purposes.

Dynamic Configurations

The /party-entities API uses below dynamic configurations for retrieval of party entities.

Dynamic Configuration	Optionality	Purpose	Reference
Party Entity Directory	Mandatory	The Party Entity Directory holds the records loaded through Industry reference data and is the source of look-ups for /party-entities API.	Party Entity Directory

Dynamic Configuration

Optionality

Purpose

Reference

Party Entity Directory

Mandatory

The Party Entity Directory holds the records loaded through Industry reference data and is the source of look-ups for /party-entities API.

Party Entity Directory

When client implementations want to look up party entity records using IBANs, additional industry reference data will be needed. Refer 3. /iban/deconstruct for more details.

Industry Reference Data

The Party Entity directory can be loaded through the industry data loads to enable the look-ups of party entity records. IPF CSM Reachability service supports ingestion of below industry reference data files to Party Entity Directory.

SWIFTRef Bank Directory Plus
SIX Bank Master
SWIFTRef Identifiers All

For more information on mapping from each industry reference data file into party entity directory, please refer Party Entity Directory.

Usage

/party-entities API can be used by the client implementations to retrieve additional details about the parties involved on the payment for identifier / address enrichment of the payments.
Party entity look up is also used by other service implementations on CSM Reachability service to perform identifier look-ups for reachability checks when the reachability requests do not have required identifiers as used by the CSM Agents for registering memberships on CSM Participants dynamic configuration.
Below CSM Reachability endpoints use party entities look up internally (Refer CSM Reachability Operations)
1. Validate Intra Entity Reachability
2. Validate CSM Reachability
3. Select CSM Agent

Request and Response

/party-entities follows below request and response structure. This section provides information on the request and response properties, for detailed API specs, please refer CSM Reachability Service API

NOTE

When an identifier provided to the endpoint matches with multiple party entity records (because it is a shared identifiers among many branches), the head office record is returned on the response. If in this case, a head office record is not found, then all the records that match with the given identifier are returned. In most cases, party entity look up should return a single record where found.
When the party entity look up source of SWIFTRef_Identifiers_All is used for look up, then all the identifiers associated with the party are aggregated and returned in the response, alongside non-identifier fields from the matched record. This is because SWIFT provides identifier level entries on Identifiers All file and the party entity records are loaded per identifier.

API Version 2

Request

Request Property	Description
entityIdentifier	The identifier that should be used to look up the Entity record in the Party Entity Directory.
entityIdentifierType	The type of identifier being used for looking up an entity. Refer Party Identifiers Explained
entityIdentifierSubType	1. The subtype of the identifier type being used for look up. 2. For BIC type identifiers, both ACCOUNT_ISSUING_BIC and SCHEME_MEMBERSHIP_BIC values will lead to retrieval of the record identifier with matching BIC value. 3. Though party entity directory holds the NCC subtype values as defined by respective industry data source (e.g. Bank Directory Plus), the /party-entities API supports the NCC subtype values as defined under ISO20022 External Clearing System codes for look-ups.
entityCountry	ISO3166-2 country code of the entity record being queried. entityCountry is required when querying records of type LEI.
entityDataSource	The industry data source that must be used for look up of the record on Party Entity Directory.

Request Property

Description

entityIdentifier

The identifier that should be used to look up the Entity record in the Party Entity Directory.

entityIdentifierType

The type of identifier being used for looking up an entity. Refer Party Identifiers Explained

entityIdentifierSubType

1. The subtype of the identifier type being used for look up.

2. For BIC type identifiers, both ACCOUNT_ISSUING_BIC and SCHEME_MEMBERSHIP_BIC values will lead to retrieval of the record identifier with matching BIC value.

3. Though party entity directory holds the NCC subtype values as defined by respective industry data source (e.g. Bank Directory Plus), the /party-entities API supports the NCC subtype values as defined under ISO20022 External Clearing System codes for look-ups.

entityCountry

ISO3166-2 country code of the entity record being queried. entityCountry is required when querying records of type LEI.

entityDataSource

The industry data source that must be used for look up of the record on Party Entity Directory.

Response

Response Property	Description
entityUniqueId	The unique ID assigned to the entity as per the mapping from respective data source into Party Entity Directory.
entityDataSource	Industry / Custom data source that has been used for look up of the party entity record.
entityType	The type of the entity where available on Party Entity Directory.
entityName	Name of the entity as per the industry / custom data source.
entityAddress	Address of the entity as mapped from industry / custom data source. The address fields are aligned to ISO20022 specified address field format.
entityIdentifiers (*)	1. A list of identifiers derived from the Party Entity Directory. Multiple identifiers of same type can be registered against a record (in case of mergers) and multiple identifiers of different types can be returned if recorded on Party Entity directory. 2. Refer Party Identifiers Explained for more details on identifier types supported on CSM Reachability Service.
+identifier	The identifier value for the entity.
+IdentifierType	The type value associated with the entity identifier.
+identifierSubType	Subtype of the identifier type returned.
entityEmail	Email for the entity as recorded on Party Entity Directory.
entityPhoneNumber	The phone number for the entity as recorded on Party Entity Directory.

Response Property

Description

entityUniqueId

The unique ID assigned to the entity as per the mapping from respective data source into Party Entity Directory.

entityDataSource

Industry / Custom data source that has been used for look up of the party entity record.

entityType

The type of the entity where available on Party Entity Directory.

entityName

Name of the entity as per the industry / custom data source.

entityAddress

Address of the entity as mapped from industry / custom data source. The address fields are aligned to ISO20022 specified address field format.

entityIdentifiers (*)

1. A list of identifiers derived from the Party Entity Directory. Multiple identifiers of same type can be registered against a record (in case of mergers) and multiple identifiers of different types can be returned if recorded on Party Entity directory.

2. Refer Party Identifiers Explained for more details on identifier types supported on CSM Reachability Service.

+identifier

The identifier value for the entity.

+IdentifierType

The type value associated with the entity identifier.

+identifierSubType

Subtype of the identifier type returned.

entityEmail

Email for the entity as recorded on Party Entity Directory.

entityPhoneNumber

The phone number for the entity as recorded on Party Entity Directory.