Party Entity Directory

Party Entity Directory is a dynamic configuration that can be used to look up Party Entities to retrieve the party entity details like identifiers and address details.

The data returned from party entity look up can be used by client implementations for payment enrichment purposes. The directory is also used during reachability check to look up identifiers used by CSM Agents for participation when the input request does not provide required identifier type.

Party Entity Directory supports ingestion from Industry reference data to enable entity look-ups.

IPF supports below industry file ingestion into Party Entity Directory: In future more data sources can be supported on Party Entity Directory if a need is identified through client requirements.

If required, client implementations can also define and implement custom ingestion into Party Entity Directory.

Sr. No.	Industry Data File	Industry Source	File Format	File Type (Full / Delta)
1	Bank Directory Plus	SWIFTRef	XML	Full, Delta
2	Identifiers All	SWIFTRef	XML, ZIP (XML)	Full, Daily Delta, Monthly Delta
3	SIX Bank Master 3.0	SIX	XML	Full

Sr. No.

Industry Data File

Industry Source

File Format

File Type (Full / Delta)

Bank Directory Plus

SWIFTRef

XML

Full, Delta

Identifiers All

SWIFTRef

XML, ZIP (XML)

Full, Daily Delta, Monthly Delta

SIX Bank Master 3.0

SIX

XML

Full

Party Entity Directory Data Structure

Similar to CSM Participants, Party Entity Directory is a generic dynamic configuration that is loaded through different industry sources in a generic way, irrespective of the format of source industry files.

Below are the properties supported on Party Entity Directory.

Party Entity Directory property	Description
entityUniqueId	A unique ID by which the entity will be known. The ID will be unique across the data source.
parentEntityId	Entity Id of the parent entity of entity represented by "EntityUniqueId". The attribute may not be loaded for all the sources until specifically requested.
groupEntityId	Entity Id of the group level entity of entity represented by "EntityUniqueId". This information may not be loaded for all the sources until specifically requested.
isHeadOffice	Indicates if the entity is a head office entity in the group.
entityDataSource	Specifies the source of the data, which can be a certain reference data source, such as 'Bank_Directory_Plus', 'Bank_Master' or 'SWIFTRef_Identifiers_All'.
entityType	Type of the Party Entity. Possible values are 'Bank' or 'Branch'. This is for information purposes only and not used during processing.
entityName	Name of Party entity.
entityAddress	Address of Party entity. The address fields on Party Entity Directory records follow ISO20022 compliant address structure. Please refer the schema for the attributes provided under the address here CSM Reachability Setting Management API
entityEmail	Email of Party Entity. Supports special characters.
entityPhoneNumber	Phone number of Party Entity. Supports special characters
entityIdentifiers	A list of identifiers associated with the entity. The Identifier types supported are BIC, NCC (National Clearing Code) and LEI.
routingIdentifiers	These are the identifiers that can be used for routing SWIFT payments to the entity using SWIFT services. The information will be available on party entity record when provided by the industry data sources.
+swiftFinPlusBic	BIC value to be used when routing the payments to the entity on SWIFT FIN PLUS service.
+swiftFinPlusDn	Distinguished name to be used when routing the payments to the entity on SWIFT FIN PLUS service using a distinguished name.
ibanIdentifiers	These are identifiers associated with the entity when IBANs are used to address the entity / accounts held with the entity.
+ibanId	IBAN ID as provided by the industry source. This information is not provided by all the sources (Only loaded for SWIFTRef Identifiers All).
+ibanBic	BIC used by the entity when issuing IBANs to the customers / accounts. This information is not provided by all the sources. (Only loaded for SWIFTRef Identifiers All)

Party Entity Directory property

Description

entityUniqueId

A unique ID by which the entity will be known. The ID will be unique across the data source.

parentEntityId

Entity Id of the parent entity of entity represented by "EntityUniqueId". The attribute may not be loaded for all the sources until specifically requested.

groupEntityId

Entity Id of the group level entity of entity represented by "EntityUniqueId". This information may not be loaded for all the sources until specifically requested.

isHeadOffice

Indicates if the entity is a head office entity in the group.

entityDataSource

Specifies the source of the data, which can be a certain reference data source, such as 'Bank_Directory_Plus', 'Bank_Master' or 'SWIFTRef_Identifiers_All'.

entityType

Type of the Party Entity. Possible values are 'Bank' or 'Branch'. This is for information purposes only and not used during processing.

entityName

Name of Party entity.

entityAddress

Address of Party entity. The address fields on Party Entity Directory records follow ISO20022 compliant address structure. Please refer the schema for the attributes provided under the address here CSM Reachability Setting Management API

entityEmail

Email of Party Entity. Supports special characters.

entityPhoneNumber

Phone number of Party Entity. Supports special characters

entityIdentifiers

A list of identifiers associated with the entity. The Identifier types supported are BIC, NCC (National Clearing Code) and LEI.

routingIdentifiers

These are the identifiers that can be used for routing SWIFT payments to the entity using SWIFT services. The information will be available on party entity record when provided by the industry data sources.

+swiftFinPlusBic

BIC value to be used when routing the payments to the entity on SWIFT FIN PLUS service.

+swiftFinPlusDn

Distinguished name to be used when routing the payments to the entity on SWIFT FIN PLUS service using a distinguished name.

ibanIdentifiers

These are identifiers associated with the entity when IBANs are used to address the entity / accounts held with the entity.

+ibanId

IBAN ID as provided by the industry source. This information is not provided by all the sources (Only loaded for SWIFTRef Identifiers All).

+ibanBic

BIC used by the entity when issuing IBANs to the customers / accounts. This information is not provided by all the sources. (Only loaded for SWIFTRef Identifiers All)

Refer to below page to know more about payment identifiers used on IPF CSM Reachability Service. Party Identifiers Explained

NOTE

Bank Directory Plus will be decommissioned by SWIFT as of November 2026 as part of SWIFTRef portfolio evolution initiative by SWIFT. Ingestion support for Bank Directory Plus will be provided on IPF until this time. Client implementations must subscribe to the evolved SWIFTRef portfolio (Payments Directory or Identifiers Directory) and start using Identifiers All file for party entity data from SWIFTRef source ahead of this date. Refer SWIFTRef Portfolio Evolution for more details.
The party entity directory records created through ingestion of Bank Directory Plus has all the identifiers of the party on the single record while an equivalent entity ingested through Identifiers All will have multiple party entity records with the same entity unique Id. This is because SWIFT provide identifier level records in Identifiers All while Bank Directory Plus provides a single entity record with all identifiers available on it. Despite the database holding the entity identifiers from Identifiers All on different records, the party entity look up provided by IPF aggregates multiple identifiers associated with the same entity when a look-up is performed using Identifiers All as the source. So a party entity look up response will look similar irrespective of whether a look-up is performed from Bank Directory Plus or Identifiers All. Refer Party Entities for more details.

Important points to note about Party Entity Directory:

All the BICs provided by the industry data sources are loaded as ACCOUNT_ISSUING_BIC on party entity directory.
The National Ids provided by industry data sources are loaded as NCCs and subtype definitions are loaded as per the industry data source. Where available, the subtype information aligned with ISO20022 aligned 'External Clearing Codes' is also loaded.
Party Entity Directory is not meant to be used for checking membership to schemes or participation to CSM Agents. For this purpose, CSM Participant dynamic configuration is used.

Setting Type

DPS v2 introduced new attribute of Setting Type. This is used for generation of all API endpoints for a particular setting. It is also used in index-config.<setting type> construct. SETTING_TYPE = "partyentity"

Searchable Fields

Searchable fields for Party Entity Directory are:

identifier
identifierType
identifierSubType
country
entityDataSource
entityUniqueId
ibanId

Indexes

DPS v2 provides an option to configure indexes for each setting. Default indexes for Party Entity Directory are:

ipf.dps.mongodb.index-config.partyentity {
    index-1 = ["status:ASC"]
    index-2 = ["source:ASC"]
    index-3 = ["values.payload.entityIdentifiers.identifier:ASC"]
    index-4 = ["values.payload.entityIdentifiers.identifierSubType:ASC"]
    index-5 = ["values.payload.entityDataSource:ASC"]
    index-6 = ["payload.entityIdentifiers.identifier:ASC"]
    index-7 = ["payload.entityIdentifiers.identifierSubType:ASC"]
    index-8 = ["payload.entityDataSource:ASC"]
    index-9 = ["values.payload.entityIdentifiers.identifierType:ASC"]
    index-10 = ["values.payload.entityAddress.country:ASC"]
    index-11 = ["payload.entityIdentifiers.identifierType:ASC"]
    index-12 = ["payload.entityAddress.country:ASC"]
    index-13 = ["processingEntity:ASC"]
    index-14 = ["values.payload.entityUniqueId:ASC"]
    index-15 = ["values.payload.ibanIdentifiers.ibanId:ASC"]
    index-16 = ["lastUpdatedAt:ASC"]
}

This can be overridden or updated. Just note that when the field is under payload, you need to provide an index like: index-x = ["values.payload.fieldX:ASC"].

Field processingEntity is added in to the setting search so for better performances is recommended that index for processingEntity is created.

Notifications

DPS v2 can provide notification after certain CRUD operation on a setting is performed. There is an option to enable notifications on setting level. Notifications are disabled by default:

ipf.csm-reachability.should-send-notification.party-entity-settings = false

History

There is an option to disable history on setting level. History is enabled by default:

ipf.csm-reachability.should-save-history.party-entity-settings = true

Party Entity Directory Mappings

Party Entity Directory mapping supports below ingestions: