IVMS-101 Format Guidelines

Overview

GTR use the IVMS101 format defined by the interVASP Standards Working Group (ISWG), using 2020 edition of IVMS101-interVASP-data-model-standard-issue-1-FINAL.pdf. This is a standardized data model used in the crypto‑financial industry to accurately exchange users’ personally identifiable information (PII) between different VASPs.

The payload to be encrypted should look like below, the ivms101 payload is as a child inside the key name “ivms101”: { … }.

{
  "ivms101": {
    //...
  }
}

Where the required information depends on Legal Person or Natural Person to make a transaction, the following structure may help you to fill the info.

One validated IVMS structure sent from Originator requires “Originator”, “Beneficiary”, “OriginatingVASP” inside, and the case is sensitive.

Following structure overviews the structure in IVMS-101, please note that the case is sensitive and name, value type (Object or Array) is also important.

{
  "ivms101": {
    "Originator": {
      "originatorPersons": [
        // LegalPerson or NaturalPerson
      ],
      "accountNumber": ["ACCOUNT NUMBER"]
    },
    "Beneficiary": {
      "beneficiaryPersons": [
        // LegalPerson or NaturalPerson
      ],
      "accountNumber": ["ACCOUNT NUMBER"]
    },
    "OriginatingVASP": {
      "originatingVASP": {
        "legalPerson": {
          // LegalPerson
        }
      }
    },
    "BeneficiaryVASP": {
      "beneficiaryVASP": {
        "legalPerson": {
          // LegalPerson
        }
      }
    }
    // option: transferPath (IntermediaryVasp)
    // option: payloadMetadata (TransliterationMethodCode)
  }
}

The necessary part to pre-fill in the JSON

Whatever you are OriginatingVASP or BeneficiaryVASP, if you initiate the request to GTR, you should preset your role in JSON (One of OriginatingVASP or BeneficiaryVASP), and you should set both the Beneficiary and Originator, please see the table below.

As API Initiator

	(Initiator) Pre-Transaction Approval	(Initiator) Post-Transaction Approval
OriginatingVASP	Yes (Your company info)	No (Leave empty)
BeneficiaryVASP	No (Leave empty)	Yes (Your company info)
Originator	Yes (Your user)	Yes (Target user)
Beneficiary	Yes (Target user)	Yes (Your user)

As Webhook Receiver

	(Receiver) Pre-Transaction Approval	(Receiver) Post-Transaction Approval
OriginatingVASP	No (Return origin in json)	Yes (Your company info, *optional)
BeneficiaryVASP	Yes (Your company info, *optional)	No (Return origin in json)
Originator	No (Return origin in json)	No (Return origin in json)
Beneficiary	No (Return origin in json)	No (Return origin in json)

Please see the organized chart also:

Necessary json-key preset in JSON by default

Please note that it is necessary to have default key-value of IVMS-101, please check section Default Key-Value of IVMS.

About Field - Originator, Beneficiary

We assume that you already have both originator person and beneficiary person info in your system, the verify target is beneficiary person, the travel rule verify request will focus on verify the beneficiary info.

As the OriginatingVASP, should make sure that you put the person info in beneficiary, and if the beneficiary and originator is the same person, you could directly use the same info for Originator and Beneficiary fields.

As the BeneficiaryVASP, the info in the Beneficiary field is to let you know the person who makes a transaction to your service.

Transaction target could be a natural person or legal person (company), it use the different structure in IVMS, please refer to the section:

Example - Natural Person
Example - Legal Person

About Field - OriginatingVASP

If you initiate the Pre-transaction travel rule verify flow, that means you are OriginatingVASP, please fill your company entity info into the corresponding field.

(For initiator) The above's example struct is following:

{
  "ivms101": {
    // Your company info (Because you're an originating VASP)
    "OriginatingVASP": {
      "originatingVASP": {
        // required, you are an legal person
        "legalPerson": {
          "countryOfRegistration": "[2-Alpha Country Code]",
          // required
          "geographicAddress": [
            {
              "country": "[2-Alpha Country Code]",
              "townName": "[Town Name]",
              "addressType": "GEOG",
              "addressLine": ["[Full Address]"]
            }
          ],
          "name": {
            "nameIdentifier": [
              {
                // required
                "legalPersonName": "[Your Company Name]",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "countryOfIssue": "[2-Alpha Country Code]",
            "nationalIdentifier": "[ID Code]",
            "nationalIdentifierType": "LEGL",
            "registrationAuthority": "[The name who (Government,Department,Company...etc) authorized this identity number]"
          }
        }
      }
    },
    "Originator": {
      // ...
    },
    "Beneficiary": {
      // ...
    }
  }
}

Once you receive the Pre-transaction travel rule request (as receiver server), you have to put your company info to BeneficiaryVASP and encrypt it back again.

{
  "ivms101": {
    // Your company info (Because you're an beneficiary VASP)
    "BeneficiaryVASP": {
      "beneficiaryVASP": {
        // required, you are an legal person
        "legalPerson": {
          "countryOfRegistration": "[2-Alpha Country Code]",
          // required
          "geographicAddress": [
            {
              "country": "[2-Alpha Country Code]",
              "townName": "[Town Name]",
              "addressType": "GEOG",
              "addressLine": ["[Full Address]"]
            }
          ],
          "name": {
            "nameIdentifier": [
              {
                // required
                "legalPersonName": "[Your Company Name]",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "countryOfIssue": "[2-Alpha Country Code]",
            "nationalIdentifier": "[ID Code]",
            "nationalIdentifierType": "LEGL",
            "registrationAuthority": "[The name who (Government,Department,Company...etc) authorized this identity number]"
          }
        }
      }
    },
    "OriginatingVASP": {
      "originatingVASP": {
        // required, you are an legal person
        "legalPerson": {
          "countryOfRegistration": "[2-Alpha Country Code]",
          // required
          "geographicAddress": [
            {
              "country": "[2-Alpha Country Code]",
              "townName": "[Town Name]",
              "addressType": "GEOG",
              "addressLine": ["[Full Address]"]
            }
          ],
          "name": {
            "nameIdentifier": [
              {
                // required
                "legalPersonName": "[Your Company Name]",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "countryOfIssue": "[2-Alpha Country Code]",
            "nationalIdentifier": "[ID Code]",
            "nationalIdentifierType": "LEGL",
            "registrationAuthority": "[The name who (Government,Department,Company...etc) authorized this identity number]"
          }
        }
      }
    },
    "Originator": {
      // ...
    },
    "Beneficiary": {
      // ...
    }
  }
}

About Field - BeneficiaryVASP

if you initiate a travel rule request for Post-transaction travel rule, that means you are BeneficiaryVASP, please fill your company entity info into the corresponding field.

The above's example struct is following:

{
  "ivms101": {
    // Your company info (Because you're an beneficiary VASP)
    "BeneficiaryVASP": {
      "beneficiaryVASP": {
        // required, you are an legal person
        "legalPerson": {
          "countryOfRegistration": "[2-Alpha Country Code]",
          // required
          "geographicAddress": [
            {
              "country": "[2-Alpha Country Code]",
              "townName": "[Town Name]",
              "addressType": "GEOG",
              "addressLine": ["[Full Address]"]
            }
          ],
          "name": {
            "nameIdentifier": [
              {
                // required
                "legalPersonName": "[Your Company Name]",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "countryOfIssue": "[2-Alpha Country Code]",
            "nationalIdentifier": "[ID Code]",
            "nationalIdentifierType": "LEGL",
            "registrationAuthority": "[The name who (Government,Department,Company...etc) authorized this identity number]"
          }
        }
      }
    },
    "Originator": {
      // ...
    },
    "Beneficiary": {
      // ...
    }
  }
}

Once you receive the Post-transaction travel rule request (as receiver server), you have to put your company info to OriginatingVASP and encrypt it back again.

{
  "ivms101": {
    // Your company info (Because you're an originating VASP)
    "OriginatingVASP": {
      "originatingVASP": {
        // required, you are an legal person
        "legalPerson": {
          "countryOfRegistration": "[2-Alpha Country Code]",
          // required
          "geographicAddress": [
            {
              "country": "[2-Alpha Country Code]",
              "townName": "[Town Name]",
              "addressType": "GEOG",
              "addressLine": ["[Full Address]"]
            }
          ],
          "name": {
            "nameIdentifier": [
              {
                // required
                "legalPersonName": "[Your Company Name]",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "countryOfIssue": "[2-Alpha Country Code]",
            "nationalIdentifier": "[ID Code]",
            "nationalIdentifierType": "LEGL",
            "registrationAuthority": "[The name who (Government,Department,Company...etc) authorized this identity number]"
          }
        }
      }
    },
    "BeneficiaryVASP": {
      "beneficiaryVASP": {
        // required, you are an legal person
        "legalPerson": {
          "countryOfRegistration": "[2-Alpha Country Code]",
          // required
          "geographicAddress": [
            {
              "country": "[2-Alpha Country Code]",
              "townName": "[Town Name]",
              "addressType": "GEOG",
              "addressLine": ["[Full Address]"]
            }
          ],
          "name": {
            "nameIdentifier": [
              {
                // required
                "legalPersonName": "[Your Company Name]",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "nationalIdentification": {
            "countryOfIssue": "[2-Alpha Country Code]",
            "nationalIdentifier": "[ID Code]",
            "nationalIdentifierType": "LEGL",
            "registrationAuthority": "[The name who (Government,Department,Company...etc) authorized this identity number]"
          }
        }
      }
    },
    "Originator": {
      // ...
    },
    "Beneficiary": {
      // ...
    }
  }
}

About Field - TransferPath and Broker Account (IntermediaryVasp)

This section describes how to use the TransferPath field and travelRuleMetadata to support broker account scenarios with intermediary VASPs.

Background

By compliance requirements, all broker accounts must comply with the travel rule policy and exchange PII (Personally Identifiable Information) with the counterparty. When the counterparty is a "broker account", there is no verification on the response message. This solution clarifies:

How the initiator VASP should send the broker account structure in the request.
How the initiator VASP can determine if a broker account is behind the receiver VASP (since there is no verification in the response message).

The key additions for broker account support are:

travelRuleMetadata — a sibling field to ivms101 in the encrypted payload, containing broker account flags and intermediary VASP counts.
TransferPath — an array inside ivms101 that lists intermediary VASPs in the transfer chain with their sequence numbers.

Usage 1 - Broker Account behind Initiator VASP

If you act on behalf of a broker account to SEND a travel rule request (assuming you are the Originating VASP), then you should structure the PII payload like this:

{
  "travelRuleMetadata": {
    // if broker account is behind the originating VASP, please add this parameters:
    "originatingVaspIntermediaryVaspCount": 1,
    "isOriginatingVaspBroker": true
  },
  "ivms101": {
    "OriginatingVASP": {
      "originatingVASP": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                // Should put broker account legal person info here
                "legalPersonName": "Axchange - Broker Account ABC",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          }
          // ...etc, the following info should be same as originator broker account
        }
      }
    },
    "TransferPath": [
      {
        "sequence": 0, // Set the main entity (e.g. "Axchange") as FIRST intermediaryVasp
        "intermediaryVasp": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Axchange", // The main entity is the intermediaryVasp
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            }
            // ...etc (main entity info)
          }
        }
      }
    ],
    "BeneficiaryVASP": {
      // empty, because you're originating VASP
    },
    "Beneficiary": {
      // ...same as current setup, put customer PII here
    }
  }
}

Key points:

Set travelRuleMetadata.isOriginatingVaspBroker to true.
Set travelRuleMetadata.originatingVaspIntermediaryVaspCount to the number of intermediary VASPs (typically 1).
In OriginatingVASP, put the broker account's legal person info.
In TransferPath, add the main entity (e.g., "Axchange") as the first intermediary VASP with sequence: 0.

Usage 2 - Broker Account behind Receiver VASP

If you act on behalf of a broker account to RECEIVE a travel rule request (assuming you are the Beneficiary VASP), you should adjust the PII payload in the response like this:

{
  "travelRuleMetadata": {
    // kept the original one if default this is exists
    "originatingVaspIntermediaryVaspCount": 1,
    "isOriginatingVaspBroker": true,
    // Should put this parameter here
    "beneficiaryVaspIntermediaryVaspCount": 1,
    "isBeneficiaryVaspBroker": true
  },
  "ivms101": {
    "BeneficiaryVASP": {
      "beneficiaryVASP": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                // Should put broker account legal person info here
                "legalPersonName": "Faster Exchange - Broker Account ABC",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          }
          // ...etc, the following info should be same as beneficiary broker account
        }
      }
    },
    "TransferPath": [
      {
        "sequence": 0, // Set the originator's main entity as FIRST intermediaryVasp
        "intermediaryVasp": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Axchange", // The originator's main entity
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            }
            // ...etc (originator main entity info)
          }
        }
      },
      {
        "sequence": 1, // Put the receiver's main entity as SECOND intermediaryVasp
        "intermediaryVasp": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Happy Service", // The receiver's main entity is intermediaryVasp
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            }
            // ...etc (receiver main entity info)
          }
        }
      }
    ],
    "OriginatingVASP": {
      // ...same as originatingVASP from the request
    },
    "Beneficiary": {
      // ...same as current setup, put customer PII here
    },
    "Originator": {
      // ...same as current setup, put customer PII here
    }
  }
}

Key points:

Add travelRuleMetadata.isBeneficiaryVaspBroker set to true.
Add travelRuleMetadata.beneficiaryVaspIntermediaryVaspCount to the number of intermediary VASPs (typically 1).
In BeneficiaryVASP, put the broker account's legal person info.
In TransferPath, append the receiver's main entity as an additional intermediary VASP with the next sequence number.

When the receiver VASP responds as a broker account, the verification response will reflect the "no verify" status:

{
  "verifyStatus": 100000,
  "verifyMessage": "Success, NO VERIFY DUE TO BROKER ACCOUNT",
  "data": {
    "requestId": "b1a765d7-1ccc-43a3-a7ea-b472f20cff97",
    "travelruleId": "gtr-bLKztgr5JHFb",
    "verifiedFields": [
      {
        "type": "111001",
        "status": 5, // INFO EXISTS, RECEIVED BUT NO VERIFY
        "message": "no verify due to broker account"
      },
      {
        "type": "110026",
        "status": 5, // INFO EXISTS, RECEIVED BUT NO VERIFY
        "message": "no verify due to broker account"
      }
    ]
    // ...other fields
  },
  "stage": "PII_VERIFICATION",
  "pending": false,
  "failed": false,
  "success": true
}

Usage 3 - Initiator VASP Wants to Know if Broker Account behind Receiver VASP

In the response, check the PII structure in response decryption:

if (decryptedPii.travelRuleMetadata.isBeneficiaryVaspBroker) {
  // The beneficiary VASP is a broker account
}

Note: If decryptedPii.travelRuleMetadata is unknown or empty, treat it as "Not a Broker Account".

Usage 4 - Receiver VASP Wants to Know if Broker Account behind Initiator VASP

In the request, check the PII structure in request decryption:

if (decryptedPii.travelRuleMetadata.isOriginatingVaspBroker) {
  // The originating VASP is a broker account
}

Note: If decryptedPii.travelRuleMetadata is unknown or empty, treat it as "Not a Broker Account".

travelRuleMetadata Fields Reference

Field	Type	Description
`isOriginatingVaspBroker`	boolean	`true` if the originating VASP is a broker account
`isBeneficiaryVaspBroker`	boolean	`true` if the beneficiary VASP is a broker account
`originatingVaspIntermediaryVaspCount`	number	Number of intermediary VASPs on the originating side
`beneficiaryVaspIntermediaryVaspCount`	number	Number of intermediary VASPs on the beneficiary side

Rules to Fill IVMS

All required fields must include a default value, even if the actual data is not available. Please refer to the Default Key-Value of IVMS section for the recommended default structure.
If you are the Originating VASP, fill your company entity information into the OriginatingVASP field. If you are the Beneficiary VASP, fill your company entity information into the BeneficiaryVASP field.
The travel rule Initiator VASP (acting as Originating VASP) is responsible for providing both Originator and Beneficiary person information in the IVMS structure when sending the request.
If the transaction target is a Legal Person, you must also include a Natural Person entry (e.g., CEO or authorized representative) in the same persons array. The Legal Person entry must be placed as the first element, followed by the Natural Person entry. For example:

beneficiaryPersons: [ {legalPerson: {...}}, {naturalPerson: {...}} ]

All Required fields

*If the required fields is not available, please put empty default value, don't fill null or undefined.

OriginatingVASP

ivms101.OriginatingVASP.originatingVASP.legalPerson.name.nameIdentifier[0].legalPersonName
ivms101.OriginatingVASP.originatingVASP.legalPerson.name.nameIdentifier[0].legalPersonNameIdentifierType
ivms101.OriginatingVASP.originatingVASP.legalPerson.nationalIdentification.nationalIdentifierType
ivms101.OriginatingVASP.originatingVASP.legalPerson.nationalIdentification.registrationAuthority
ivms101.OriginatingVASP.originatingVASP.legalPerson.nationalIdentification.countryOfIssue
ivms101.OriginatingVASP.originatingVASP.legalPerson.nationalIdentification.nationalIdentifier
ivms101.OriginatingVASP.originatingVASP.legalPerson.geographicAddress[].country
ivms101.OriginatingVASP.originatingVASP.legalPerson.geographicAddress[].townName
ivms101.OriginatingVASP.originatingVASP.legalPerson.geographicAddress[].addressType
ivms101.OriginatingVASP.originatingVASP.legalPerson.geographicAddress[].addressLine
ivms101.OriginatingVASP.originatingVASP.legalPerson.countryOfRegistration

BeneficiaryVASP

ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.name.nameIdentifier[0].legalPersonName
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.name.nameIdentifier[0].legalPersonNameIdentifierType
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.nationalIdentification.nationalIdentifierType
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.nationalIdentification.registrationAuthority
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.nationalIdentification.countryOfIssue
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.nationalIdentification.nationalIdentifier
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.geographicAddress[0].country
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.geographicAddress[0].townName
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.geographicAddress[0].addressType
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.geographicAddress[0].addressLine
ivms101.BeneficiaryVASP.beneficiaryVASP.legalPerson.countryOfRegistration

Originator - Common

ivms101.Originator.accountNumber

Originator - Natural Person

ivms101.Originator.originatorPersons[0].naturalPerson.name.nameIdentifier[0].primaryIdentifier ivms101.Originator.originatorPersons[0].naturalPerson.name.nameIdentifier[0].secondaryIdentifier ivms101.Originator.originatorPersons[0].naturalPerson.name.nameIdentifier[0].nameIdentifierType

ivms101.Originator.originatorPersons[0].naturalPerson.name.localNameIdentifier[0].primaryIdentifier
ivms101.Originator.originatorPersons[0].naturalPerson.name.localNameIdentifier[0].secondaryIdentifier
ivms101.Originator.originatorPersons[0].naturalPerson.name.localNameIdentifier[0].nameIdentifierType
ivms101.Originator.originatorPersons[0].naturalPerson.dateAndPlaceOfBirth.placeOfBirth
ivms101.Originator.originatorPersons[0].naturalPerson.dateAndPlaceOfBirth.dateOfBirth
ivms101.Originator.originatorPersons[0].naturalPerson.customerIdentification
ivms101.Originator.originatorPersons[0].naturalPerson.countryOfResidence

Originator - Legal Person

ivms101.Originator.originatorPersons[0].legalPerson.name.nameIdentifier[0].legalPersonName
ivms101.Originator.originatorPersons[0].legalPerson.name.nameIdentifier[0].legalPersonNameIdentifierType
ivms101.Originator.originatorPersons[0].legalPerson.customerIdentification
ivms101.Originator.originatorPersons[0].legalPerson.countryOfRegistration
ivms101.Originator.originatorPersons[1].naturalPerson.name.nameIdentifier[0].primaryIdentifier
ivms101.Originator.originatorPersons[1].naturalPerson.name.nameIdentifier[0].secondaryIdentifier
ivms101.Originator.originatorPersons[1].naturalPerson.name.nameIdentifier[0].nameIdentifierType
ivms101.Originator.originatorPersons[1].naturalPerson.name.localNameIdentifier[0].primaryIdentifier
ivms101.Originator.originatorPersons[1].naturalPerson.name.localNameIdentifier[0].secondaryIdentifier
ivms101.Originator.originatorPersons[1].naturalPerson.name.localNameIdentifier[0].nameIdentifierType
ivms101.Originator.originatorPersons[1].naturalPerson.dateAndPlaceOfBirth.placeOfBirth
ivms101.Originator.originatorPersons[1].naturalPerson.dateAndPlaceOfBirth.dateOfBirth
ivms101.Originator.originatorPersons[1].naturalPerson.customerIdentification
ivms101.Originator.originatorPersons[1].naturalPerson.countryOfResidence

Beneficiary - Common

ivms101.Beneficiary.accountNumber

Beneficiary - Natural Person

ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.name.nameIdentifier[0].primaryIdentifier ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.name.nameIdentifier[0].secondaryIdentifier ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.name.nameIdentifier[0].nameIdentifierType

ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.name.localNameIdentifier[0].primaryIdentifier
ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.name.localNameIdentifier[0].secondaryIdentifier
ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.name.localNameIdentifier[0].nameIdentifierType
ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.dateAndPlaceOfBirth.placeOfBirth
ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.dateAndPlaceOfBirth.dateOfBirth
ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.customerIdentification
ivms101.Beneficiary.beneficiaryPersons[0].naturalPerson.countryOfResidence

Beneficiary - Legal Person

ivms101.Beneficiary.beneficiaryPersons[0].legalPerson.name.nameIdentifier[0].legalPersonName
ivms101.Beneficiary.beneficiaryPersons[0].legalPerson.name.nameIdentifier[0].legalPersonNameIdentifierType
ivms101.Beneficiary.beneficiaryPersons[0].legalPerson.customerIdentification
ivms101.Beneficiary.beneficiaryPersons[0].legalPerson.countryOfRegistration
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.name.nameIdentifier[0].primaryIdentifier
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.name.nameIdentifier[0].secondaryIdentifier
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.name.nameIdentifier[0].nameIdentifierType
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.name.localNameIdentifier[0].primaryIdentifier
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.name.localNameIdentifier[0].secondaryIdentifier
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.name.localNameIdentifier[0].nameIdentifierType
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.dateAndPlaceOfBirth.placeOfBirth
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.dateAndPlaceOfBirth.dateOfBirth
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.customerIdentification
ivms101.Beneficiary.beneficiaryPersons[1].naturalPerson.countryOfResidence

Example - Natural Person

[
  {
    // example fields below, please refer to above naturalPerson structure
    "naturalPerson": {
      // required
      "dateAndPlaceOfBirth": {
        "placeOfBirth": "US",
        "dateOfBirth": "1986-11-21"
      },
      // required
      "name": {
        "localNameIdentifier": [
          {
            "nameIdentifierType": "LEGL",
            "primaryIdentifier": "サトシ",
            "secondaryIdentifier": "ナカモト"
          }
        ],
        "nameIdentifier": [
          {
            "nameIdentifierType": "LEGL",
            "primaryIdentifier": "Satoshi",
            "secondaryIdentifier": "Nakamoto"
          }
        ]
      },
      // optional
      "geographicAddress": [
        {
          "addressType": "GEOG",
          "streetName": "Potential Street",
          "buildingNumber": "123",
          "buildingName": "Cheese Hut",
          "postCode": "91361",
          "townName": "Thousand Oaks",
          "countrySubDivision": "California",
          "country": "US"
        }
      ],
      // optional
      "nationalIdentification": {
        "nationalIdentifier": "1032903940290499SDF3-40DA024",
        "nationalIdentifierType": "CCPT",
        "countryOfIssue": "HK"
      },
      // required
      "customerIdentification": "10929392485393",
      // required
      "countryOfResidence": "US"
    }
  }
]

Example - Legal Person

[
  // required: naturalPerson or legalPerson
  // NOTE: if you send to legalPerson, please fill [{naturalPerson:{}},{legalPerson:{}}] both, the natural person only need to given [{naturalPerson}]
  {
    "legalPerson": {
      // required, nameIdentifier*, localNameIdentifier, phoneticNameIdentifier
      "name": {
        "nameIdentifier": [
          {
            "legalPersonName": "Paycase Inc",
            "legalPersonNameIdentifierType": "LEGL" // Usually Fixed as LEGL // for legal person: LEGL, SHRT, TRAD
          }
        ]
      },
      // optional, For Company Legal Person use RAID and fill your company ID in nationalIdentifier
      "nationalIdentification": {
        // RAID is means nationalIdentifier is company ID in authority coutnry
        "nationalIdentifierType": "RAID", // ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC
        // GLEIF code (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)
        "registrationAuthority": "RA000388",
        "countryOfIssue": "HK",
        // (i.e: Your Company ID from authroity)
        "nationalIdentifier": "38429049028390482" // ^[a-zA-Z0-9' ]{1,35}$
      },
      // optional
      "geographicAddress": [
        // SAME AS Originator's geographicAddress
      ],
      // required,  (i.e: customer id from originator service)
      "customerIdentification": "0x3E9181d09E56AdEF3bbc8BAb664Ce6B268Bf6e62",
      // required
      "countryOfRegistration": "HK" // ISO-3166-1 alpha-2 codes
    }
  },
  // required both legalPerson (ex: CEO name) and naturalPerson
  {
    // example fields below, please refer to above naturalPerson structure
    "naturalPerson": {
      // required
      "dateAndPlaceOfBirth": {
        "placeOfBirth": "US",
        "dateOfBirth": "1986-11-21"
      },
      // required
      "name": {
        "localNameIdentifier": [
          {
            "nameIdentifierType": "LEGL",
            "primaryIdentifier": "サトシ",
            "secondaryIdentifier": "ナカモト"
          }
        ],
        "nameIdentifier": [
          {
            "nameIdentifierType": "LEGL",
            "primaryIdentifier": "Satoshi",
            "secondaryIdentifier": "Nakamoto"
          }
        ]
      },
      // optional
      "geographicAddress": [
        {
          "addressType": "GEOG",
          "streetName": "Potential Street",
          "buildingNumber": "123",
          "buildingName": "Cheese Hut",
          "postCode": "91361",
          "townName": "Thousand Oaks",
          "countrySubDivision": "California",
          "country": "US"
        }
      ],
      // optional
      "nationalIdentification": {
        "nationalIdentifier": "1032903940290499SDF3-40DA024",
        "nationalIdentifierType": "CCPT",
        "countryOfIssue": "HK"
      },
      // required
      "customerIdentification": "10929392485393",
      // required
      "countryOfResidence": "US"
    }
  }
]

About Field - specificNationalIdentifications (Multiple ID Documents)

IVMS101 gives a person exactly one nationalIdentification object. When your KYC record holds more than one identity document for the same customer — a national ID card and a passport, for example — put those documents in specificNationalIdentifications, which sits beside nationalIdentification inside naturalPerson and legalPerson.

specificNationalIdentifications is a customized field. It is not part of the IVMS101 2020 standard, and neither are its dateOfIssue and dateOfExpiry child fields. Every JSON example in these guidelines marks it as customized. A counterparty that parses only standard IVMS101 ignores the whole object, which is why nationalIdentification must still be filled as before — see rule 2 below.

Leave room for a future change. Upstream IVMS101 has not yet released a standard way to carry more than one identity document per person, so specificNationalIdentifications is GTR's interim design. If a later edition of IVMS101 publishes an official structure for this, GTR will follow the standard and notify integrating VASPs to migrate, because interoperability should rest on the standard rather than on a GTR extension. Build this field so it can be changed: keep the translation between your KYC records and the slot keys in one place instead of spreading it through your codebase, do not store the slot key as an identifier inside your own records, and expect the field name, the key format, or the assigned Verify Fields IDs to move in a future revision of this page.

specificNationalIdentifications is an object with a closed set of pre-defined keys, not an array. Each key is one fixed slot, named after the document type it holds:

ID_<NATIONAL_IDENTIFIER_TYPE>

<NATIONAL_IDENTIFIER_TYPE> is one of the nationalIdentifierType values: ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC. One slot per type — a KYC record holds a single document of each kind, so there is no second passport slot and no ordinal in the key.

// customized field, not IVMS101 standard
"specificNationalIdentifications": {
  "ID_IDCD": {
    // IVMS101 nationalIdentification fields
    "nationalIdentifier": "A123456789",
    "nationalIdentifierType": "IDCD",
    "countryOfIssue": "TW",
    // customized fields, optional, ISO 8601 date (YYYY-MM-DD)
    "dateOfIssue": "2019-04-08",
    "dateOfExpiry": "2029-04-07"
  },
  "ID_CCPT": {
    "nationalIdentifier": "3100923049",
    "nationalIdentifierType": "CCPT",
    "countryOfIssue": "TW",
    "dateOfIssue": "2021-11-30",
    "dateOfExpiry": "2031-11-29"
  }
}

Slot value fields

Field	Source	Requirement
`nationalIdentifier`	IVMS101	Required. The document number, `^[a-zA-Z0-9' ]{1,35}$`
`nationalIdentifierType`	IVMS101	Required. Must equal the type in the slot key
`countryOfIssue`	IVMS101	Required. ISO-3166-1 alpha-2 code
`registrationAuthority`	IVMS101	Legal person registration numbers only, GLEIF code
`dateOfIssue`	Customized	Optional. The date the document was issued, ISO 8601 `YYYY-MM-DD`
`dateOfExpiry`	Customized	Optional. The date the document expires, ISO 8601 `YYYY-MM-DD`. Omit it for a document that does not expire

The first four fields keep their IVMS101 names and formats. The two customized fields follow the same naming style as the IVMS101 fields around them: lowerCamelCase, and <value>Of<qualifier> to match countryOfIssue and dateOfBirth. They take the same date format as dateOfBirth. Omit an unknown date rather than sending "" or a partial value such as 2029-04.

Why fixed keys instead of an array

Earlier drafts carried the extra documents in an array ("additional": [ { "nationalIdentification": { ... } } ]). That form is not used. The reason is Verify Fields.

A Verify Field is a single numeric ID that both VASPs must resolve to exactly one value in the payload: the Initiator lists the ID in expectVerifyFields, the Receiver returns a result carrying the same ID, and the two sides only agree if that ID means the same JSON path on both sides. The mapping from a Verify Field ID to a JSON path therefore has to be one-to-one and fixed in advance.

An array cannot provide that:

The path of a document depends on how many documents happen to precede it. The same passport sits at ...[1] in today's payload and at ...[0] in tomorrow's, once the customer's ID card is dropped from the record. A Verify Field ID pinned to ...[1] would address a different document in every request.
The Receiver cannot tell which document the Initiator wanted verified, and cannot report "passport matched, ID card did not" without ambiguity.
Transmitted Content has the same problem: its manifest maps fieldId onto fieldPath, and a shifting array position moves the path of content that never changed.

A fixed slot key is a constant known at design time. ...specificNationalIdentifications.ID_CCPT.nationalIdentifier is the same path in every payload from every VASP, so each slot can be given its own permanently assigned Verify Field ID: one slot ↔ one Verify Field ID ↔ one manifest entry.

That is also why the key set is one slot per document type and nothing more. Every slot needs a permanently assigned Verify Field ID, so the key space has to stay finite and fully enumerated.

Slot keys

`nationalIdentifierType`	Slot key	Applies to
ISO20022	`ID_ISO20022`	Natural Person, Legal Person
ARNU	`ID_ARNU`	Natural Person, Legal Person
CCPT	`ID_CCPT`	Natural Person, Legal Person
RAID	`ID_RAID`	Legal Person only
DRLC	`ID_DRLC`	Natural Person, Legal Person
FIIN	`ID_FIIN`	Natural Person, Legal Person
TXID	`ID_TXID`	Natural Person, Legal Person
SOCS	`ID_SOCS`	Natural Person, Legal Person
IDCD	`ID_IDCD`	Natural Person, Legal Person
LEIX	`ID_LEIX`	Legal Person only
MISC	`ID_MISC`	Natural Person, Legal Person

Rules

The field is optional. Omit it entirely when the customer has only one identity document; do not send null, {}, or slots filled with empty strings. This is an exception to the default-value rule in Rules to Fill IVMS — an empty slot is a slot the counterparty will report as missing.
Keep filling nationalIdentification exactly as you do today. It remains the IVMS101-standard field that non-GTR consumers read, and it holds the person's primary document.
specificNationalIdentifications is the complete addressable set: every document you disclose appears in exactly one slot, including the document you also put in nationalIdentification. For the four IVMS101 fields they share, the mirrored slot and nationalIdentification must carry identical values; the customized dates exist only in the slot. The duplication is deliberate — nationalIdentification preserves IVMS101 interoperability, and the slot is what a Verify Field ID can point at.
The nationalIdentifierType inside a slot must equal the type in the slot key. ID_CCPT must contain "nationalIdentifierType": "CCPT".
One document per type. If your record somehow holds two documents of the same type, transmit the one used for KYC; there is no second slot for that type.
A slot value uses the same object shape as nationalIdentification — nationalIdentifier, nationalIdentifierType, countryOfIssue, plus registrationAuthority for legal person registration numbers — and may additionally carry the optional dateOfIssue and dateOfExpiry extension fields described above.
RAID and LEIX are body-corporate / legal-entity codes, so those two slots are only valid inside legalPerson.
The same document must stay in the same slot for the lifetime of a request, including when the counterparty echoes the payload back, otherwise verify results and transmitted content hashes will not line up.
Any key outside the enumerated set — a self-invented slot name such as ID_FIRST_CCPT, or a field inside a slot other than the six listed above — carries no Verify Field ID and is not processed. It is still encrypted and still hashed into Transmitted Content, so do not park free-form notes there.

Example - Natural Person with two documents

{
  "naturalPerson": {
    // ... name, dateAndPlaceOfBirth, customerIdentification, countryOfResidence as usual
    // the primary document, unchanged IVMS101 field
    "nationalIdentification": {
      "nationalIdentifier": "A123456789",
      "nationalIdentifierType": "IDCD",
      "countryOfIssue": "TW"
    },
    // CUSTOMIZED FIELD (not IVMS101 standard)
    // the full addressable set, including a mirror of the primary document above
    "specificNationalIdentifications": {
      "ID_IDCD": {
        "nationalIdentifier": "A123456789",
        "nationalIdentifierType": "IDCD",
        "countryOfIssue": "TW",
        "dateOfIssue": "2019-04-08"
        // a national ID card that does not expire: omit dateOfExpiry
      },
      "ID_CCPT": {
        "nationalIdentifier": "3100923049",
        "nationalIdentifierType": "CCPT",
        "countryOfIssue": "TW",
        "dateOfIssue": "2021-11-30",
        "dateOfExpiry": "2031-11-29"
      }
    }
  }
}

Example - Legal Person with two documents

{
  "legalPerson": {
    // ... name, customerIdentification, countryOfRegistration as usual
    "nationalIdentification": {
      "nationalIdentifierType": "RAID",
      "registrationAuthority": "RA000388",
      "countryOfIssue": "HK",
      "nationalIdentifier": "38429049028390482"
    },
    // CUSTOMIZED FIELD (not IVMS101 standard)
    // the full addressable set, including a mirror of the primary document above
    "specificNationalIdentifications": {
      "ID_RAID": {
        "nationalIdentifierType": "RAID",
        "registrationAuthority": "RA000388",
        "countryOfIssue": "HK",
        "nationalIdentifier": "38429049028390482",
        "dateOfIssue": "2016-02-17"
      },
      "ID_LEIX": {
        "nationalIdentifierType": "LEIX",
        "countryOfIssue": "HK",
        "nationalIdentifier": "5493001KJTIIGC8Y1R12",
        "dateOfIssue": "2022-06-01",
        "dateOfExpiry": "2026-05-31"
      }
    }
  }
}

Default Key-Value of IVMS

To avoiding null pointer issue, we will strongly recommend you to fill in the following key-value when you integrate IVMS-101, please check the folling empty structure, even you don't have the fields data, please fill as default.

For Natural Person Default

{
  ...
  {
      "naturalPerson": {
        // required
        "name": {
          "localNameIdentifier": [ // at least given not-null default element
            {
              "nameIdentifierType": "LEGL",
              "primaryIdentifier": "",
              "secondaryIdentifier": ""
            }
          ],
          "nameIdentifier": [ // at least given not-null default element
            {
              "nameIdentifierType": "LEGL",
              "primaryIdentifier": "",
              "secondaryIdentifier": ""
            }
          ],
          "phoneticNameIdentifier": [] // ok to be empty
        },

        // required
        "dateAndPlaceOfBirth": {
          "placeOfBirth": "", 
          "dateOfBirth": ""
        },
        
        // optional: if you use one of field, please set default like below
        "geographicAddress": [
          // at least given not-null default element
          {
            "addressType": "GEOG",
            "townName": "",
            "addressLine": [
              // at least given not-null default element
              ""
            ], 
            "country": "",
            "postCode": ""
          }
        ],
        // optional: can leave all key unset
        "nationalIdentification": {
          "nationalIdentifier": "",
          "nationalIdentifierType": "",
          "countryOfIssue": ""
        },
        // required
        "customerIdentification": "",
        // required
        "countryOfResidence": ""
      }
  }
}

For Legal Person Default

{
  ...
      {
          "legalPerson": {
            // required
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            // optional: can leave all key unset
            "nationalIdentification": {
              "nationalIdentifierType": "RAID",
              "registrationAuthority": "",
              "countryOfIssue": "",
              "nationalIdentifier": "" 
            },

            // optional: if you use one of field, please set default like below
            "geographicAddress": [
              // at least given not-null default element
              {
                "addressType": "GEOG",
                "townName": "",
                "addressLine": [
                  // at least given not-null default element
                  ""
                ], 
                "country": "",
                "postCode": ""
              }
            ],
            // required
            "customerIdentification": "",
            // required
            "countryOfRegistration": "HK"
          }
        },
        // required both legalPerson (ex: CEO name) and naturalPerson
        {
          "naturalPerson": {
            // required
            "dateAndPlaceOfBirth": {
              "placeOfBirth": "",
              "dateOfBirth": ""
            },
            // required
            "name": {
              "localNameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "",
                  "secondaryIdentifier": ""
                }
              ],
              "nameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "",
                  "secondaryIdentifier": ""
                }
              ]
            },
            // optional: if you use one of field, please set default like below
            "geographicAddress": [
              {
                "addressType": "GEOG",
                "townName": "",
                "addressLine": [
                  // at least given not-null default element
                  ""
                ], 
                "country": "",
                "postCode": ""
              }
            ],
            // optional: can leave all key unset
            "nationalIdentification": {
              "nationalIdentifier": "",
              "nationalIdentifierType": "",
              "countryOfIssue": ""
            },

            // required
            "customerIdentification": "",
            
            // required
            "countryOfResidence": ""
          }
        }
      ],
      "accountNumber": [""]
    }
...
}

Full Example of IVMS

The detail of structure definition is below, the following structure is a full example of IVMS-101.

{
  "ivms101": {
    "OriginatingVASP": {
      "originatingVASP": {
        // required
        "legalPerson": {
          // required, nameIdentifier*, localNameIdentifier, phoneticNameIdentifier
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Originator VASP Company Name - VVVV Inc.", // Enum Code: 121001, Legal Person Name
                "legalPersonNameIdentifierType": "LEGL" // Usually Fixed as LEGL // for legal person: LEGL, SHRT, TRAD
              }
            ]
          },
          // required, For Company Legal Person use RAID and fill your company ID in nationalIdentifier
          "nationalIdentification": {
            // nationalIdentifierType: ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC,
            "nationalIdentifierType": "RAID", // Enum Code: 121002, Legal Person National Identifier ID Type
            // registrationAuthority: GLEIF code (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)
            "registrationAuthority": "RA000388", // Enum Code: 121004, Legal Person National Identifier Registration Authority ID
            // countryOfIssue: ISO 3166-1 alpha-2 codes
            "countryOfIssue": "HK", // Enum Code: 121005, Legal Person National Identifier Country of Issue
            // nationalIdentifier: (i.e: Your Company ID from authroity)
            "nationalIdentifier": "38429049028390482" // Enum Code: 121003, Legal Person National Identifier ID
          },
          // required
          "geographicAddress": [
            {
              // required
              "country": "HK", // Enum Code: 121007, ISO 3166-1 alpha-2 codes
              "townName": "Hong Kong", // Enum Code: 121008, Legal Person Address - Town Name
              "addressType": "GEOG", // HOME, BIZZ, GEOG
              "addressLine": ["Please fill your address here"], // Enum Code: 121009, Legal Person Address - Address Lines
              "postCode": "TT7643", // Enum Code: 121018, Legal Person Address - Post Code

              // optional:
              "department": "OfficeOfTheCEO", // Enum Code: 121010, Legal Person Address - Department
              "subDepartment": "InternalAudit8562", // Enum Code: 121011, Legal Person Address - Sub Department
              "streetName": "SiliconAlley65", // Enum Code: 121012, Legal Person Address - Street
              "buildingNumber": "J4H6", // Enum Code: 121013, Legal Person Address - Building Number
              "buildingName": "VirtualTower200", // Enum Code: 121014, Legal Person Address - Building Name
              "floor": "Floor94", // Enum Code: 121015, Legal Person Address - Floor
              "postBox": "CB842", // Enum Code: 121016, Legal Person Address - Postbox
              "room": "BionicRoom38", // Enum Code: 121017, Legal Person Address - Room
              "townLocationName": "E-Sector", // Enum Code: 121019, Legal Person Address - Town Location
              "districtName": "BlockchainDistrict", // Enum Code: 121020, Legal Person Address - District Name
              "countrySubDivision": "E-Province" // Enum Code: 121021, Legal Person Address - Country of Sub Division
            }
          ],
          // required
          "countryOfRegistration": "HK" // Enum Code: 121022, Legal Person Country of Registration
        }
      }
    },
    "BeneficiaryVASP": {
      "beneficiaryVASP": {
        // required
        "legalPerson": {
          // required, nameIdentifier*, localNameIdentifier, phoneticNameIdentifier
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Beneficiary VASP Company Name - VVVV Inc.", // Enum Code: 131001, Legal Person Name
                "legalPersonNameIdentifierType": "LEGL" // Usually Fixed as LEGL // for legal person: LEGL, SHRT, TRAD
              }
            ]
          },
          // required, For Company Legal Person use RAID and fill your company ID in nationalIdentifier
          "nationalIdentification": {
            // nationalIdentifierType: ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC,
            "nationalIdentifierType": "RAID", // Enum Code: 131002, Legal Person National Identifier ID Type
            // registrationAuthority: GLEIF code (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)
            "registrationAuthority": "RA000388", // Enum Code: 131004, Legal Person National Identifier Registration Authority ID
            // countryOfIssue: ISO 3166-1 alpha-2 codes
            "countryOfIssue": "HK", // Enum Code: 131005, Legal Person National Identifier Country of Issue
            // nationalIdentifier: (i.e: Your Company ID from authroity)
            "nationalIdentifier": "38429049028390482" // Enum Code: 131003, Legal Person National Identifier ID
          },
          // required
          "geographicAddress": [
            {
              // required
              "country": "HK", // Enum Code: 131007, ISO 3166-1 alpha-2 codes
              "townName": "Hong Kong", // Enum Code: 131008, Legal Person Address - Town Name
              "addressType": "GEOG", // HOME, BIZZ, GEOG
              "addressLine": ["Please fill your address here"], // Enum Code: 131009, Legal Person Address - Address Lines
              "postCode": "TT7643", // Enum Code: 131018, Legal Person Address - Post Code

              // optional:
              "department": "OfficeOfTheCEO", // Enum Code: 131010, Legal Person Address - Department
              "subDepartment": "InternalAudit8562", // Enum Code: 131011, Legal Person Address - Sub Department
              "streetName": "SiliconAlley65", // Enum Code: 131012, Legal Person Address - Street
              "buildingNumber": "J4H6", // Enum Code: 131013, Legal Person Address - Building Number
              "buildingName": "VirtualTower200", // Enum Code: 131014, Legal Person Address - Building Name
              "floor": "Floor94", // Enum Code: 131015, Legal Person Address - Floor
              "postBox": "CB842", // Enum Code: 131016, Legal Person Address - Postbox
              "room": "BionicRoom38", // Enum Code: 131017, Legal Person Address - Room
              "townLocationName": "E-Sector", // Enum Code: 131019, Legal Person Address - Town Location
              "districtName": "BlockchainDistrict", // Enum Code: 131020, Legal Person Address - District Name
              "countrySubDivision": "E-Province" // Enum Code: 131021, Legal Person Address - Country of Sub Division
            }
          ],
          // required
          "countryOfRegistration": "HK" // Enum Code: 131022, Legal Person Country of Registration
        }
      }
    },
    "Originator": {
      // required, the user wallet address
      "accountNumber": [
        "1GURHee2JsCkdpxVisjbjAeNhbDbGub8R4" // Enum Code: 103023, Max 100 text, ^[a-zA-Z0-9' ]{1,100}$
      ],
      "originatorPersons": [
        {
          "naturalPerson": {
            // required
            "dateAndPlaceOfBirth": {
              "placeOfBirth": "US", // Enum Code: 100024, ISO-3166-1 alpha-2 codes
              "dateOfBirth": "1986-11-21" // Enum Code: 100025, Natural Person Date of Birth
            },
            // required
            "name": {
              // have: nameIdentifier (required), localNameIdentifier (required), phoneticNameIdentifier (optional)
              "localNameIdentifier": [
                {
                  // nameIdentifierType: Usually Fixed as LEGL // for natural person: ALIA, BIRT, MAID, LEGL, MISC
                  "nameIdentifierType": "LEGL",
                  // primaryIdentifier: lastname, or lastname + firstname
                  "primaryIdentifier": "サトシ",
                  // secondaryIdentifier: firstname, or leave empty if cannot recognize
                  // Receivers must not rely on this split, see Parameters Description
                  "secondaryIdentifier": "ナカモト"
                }
              ], // Enum Code: 100027, Natural Person Local Name
              "nameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "Satoshi",
                  "secondaryIdentifier": "Nakamoto"
                }
              ], // Enum Code: 100026, Natural Person Name
              // optional
              "phoneticNameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "Satoshi",
                  "secondaryIdentifier": "Nakamoto"
                }
              ] // Enum Code: 100028, Natural Person Phonetic Name
            },
            // optional
            "geographicAddress": [
              {
                // required (if have):
                "addressType": "GEOG", // HOME, BIZZ, GEOG
                // townName can also be city / town
                "townName": "VirtualTown", // Enum Code: 100030, Natural Person Address - Town Name
                "addressLine": ["Line489", "Line762"], // Enum Code: 100031, Natural Person Address - Address Lines
                "country": "US", // Enum Code: 100029, ISO-3166-1 alpha-2 codes
                "postCode": "TT7643", // Enum Code: 100040, Natural Person Address - Post Code
                
                // optional:
                "department": "OfficeOfTheCEO", // Enum Code: 100032, Natural Person Address - Department
                "subDepartment": "InternalAudit8562", // Enum Code: 100033, Natural Person Address - Sub Department
                "streetName": "SiliconAlley65", // Enum Code: 100034, Natural Person Address - Street
                "buildingNumber": "J4H6", // Enum Code: 100035, Natural Person Address - Building Number
                "buildingName": "VirtualTower200", // Enum Code: 100036, Natural Person Address - Building Name
                "floor": "Floor94", // Enum Code: 100037, Natural Person Address - Floor
                "postBox": "CB842", // Enum Code: 100038, Natural Person Address - Postbox
                "room": "BionicRoom38", // Enum Code: 100039, Natural Person Address - Room
                "townLocationName": "E-Sector", // Enum Code: 100041, Natural Person Address - Town Location
                "districtName": "BlockchainDistrict", // Enum Code: 100042, Natural Person Address - District Name
                // countrySubDivision is also a country state
                "countrySubDivision": "E-Province" // Enum Code: 100043, Natural Person Address - Country of Sub Division
              }
            ],
            // optional
            "nationalIdentification": {
              // nationalIdentifier, for example Passport number (CCPT), ^[a-zA-Z0-9' ]{1,35}$
              "nationalIdentifier": "1032903940290499SDF3-40DA024", // Enum Code: 100045, Natural Person National ID
              // CCPT: Passport, ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC
              "nationalIdentifierType": "CCPT", // Enum Code: 100044, Natural Person National ID - Type
              // registrationAuthority 不填寫，外交部發行的不是法人單位，是政府單位。don't fill the registrationAuthority, the identity approved by immigration affairs is government department, not legal person
              "countryOfIssue": "HK" // Enum Code: 100046, Natural Person National ID - Country Of Issue
            },
            // optional, CUSTOMIZED FIELD (not IVMS101 standard): every identity document, one fixed slot each
            // slot key is ID_<nationalIdentifierType>; see section: About Field - specificNationalIdentifications
            "specificNationalIdentifications": {
              // mirrors the nationalIdentification above, same four IVMS101 values
              "ID_CCPT": {
                "nationalIdentifier": "1032903940290499SDF3-40DA024", // Enum Code: 100062, Natural Person National ID - passport number
                "nationalIdentifierType": "CCPT", // must equal the type in the slot key
                "countryOfIssue": "HK",
                // customized fields, optional, ISO 8601 date (YYYY-MM-DD), no Enum Code assigned
                "dateOfIssue": "2021-11-30",
                "dateOfExpiry": "2031-11-29"
              },
              // a second document of a different type
              "ID_DRLC": {
                "nationalIdentifier": "D1234567", // Enum Code: 100064, Natural Person National ID - Driver's License Number
                "nationalIdentifierType": "DRLC",
                "countryOfIssue": "US",
                "dateOfIssue": "2020-03-15",
                "dateOfExpiry": "2030-03-14"
              }
            },
            // required, (i.e: customer id from originator service)
            "customerIdentification": "10929392485393", // Enum Code: 100047, Natural Person Customer ID
            // required
            "countryOfResidence": "US" // Enum Code: 100048, Natural Person Country of Residence
          }
        }
      ]
    },
    "Beneficiary": {
      "beneficiaryPersons": [
        // required: naturalPerson or legalPerson
        // NOTE: if you send to legalPerson, please fill [{naturalPerson:{}},{legalPerson:{}}] both, the natural person only need to given [{naturalPerson}]
        {
          "legalPerson": {
            // required, nameIdentifier*, localNameIdentifier, phoneticNameIdentifier
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Paycase Inc", // Enum Code: 111001, Legal Person Name
                  "legalPersonNameIdentifierType": "LEGL" // Usually Fixed as LEGL // for legal person: LEGL, SHRT, TRAD
                }
              ]
            },
            // optional, For Company Legal Person use RAID and fill your company ID in nationalIdentifier
            "nationalIdentification": {
              // RAID is means nationalIdentifier is company ID in authority coutnry
              "nationalIdentifierType": "RAID", // Enum Code: 111002, ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC
              // GLEIF code (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)
              "registrationAuthority": "RA000388", // Enum Code: 111004, Legal Person National Identifier Registration Authority ID
              "countryOfIssue": "HK", // Enum Code: 111005, Legal Person National Identifier Country of Issue
              // (i.e: Your Company ID from authroity)
              "nationalIdentifier": "38429049028390482" // Enum Code: 111003, ^[a-zA-Z0-9' ]{1,35}$
            },
            // optional, CUSTOMIZED FIELD (not IVMS101 standard): every registration document, one fixed slot each
            // slot key is ID_<nationalIdentifierType>; see section: About Field - specificNationalIdentifications
            "specificNationalIdentifications": {
              // mirrors the nationalIdentification above, same IVMS101 values
              "ID_RAID": {
                "nationalIdentifierType": "RAID", // must equal the type in the slot key
                "registrationAuthority": "RA000388",
                "countryOfIssue": "HK",
                "nationalIdentifier": "38429049028390482", // Enum Code: 111052, Legal Person National ID - Business registration number provided by the authority
                // customized field, optional, ISO 8601 date (YYYY-MM-DD), no Enum Code assigned
                "dateOfIssue": "2016-02-17"
              },
              // LEIX and RAID slots are valid for legalPerson only
              "ID_LEIX": {
                "nationalIdentifierType": "LEIX",
                "countryOfIssue": "HK",
                "nationalIdentifier": "5493001KJTIIGC8Y1R12", // Enum Code: 111058, Legal Person National ID - Global legal entity identification number
                "dateOfIssue": "2022-06-01",
                "dateOfExpiry": "2026-05-31"
              }
            },
            // optional
            "geographicAddress": [
              // SAME AS Originator's geographicAddress
            ],
            // required,  (i.e: customer id from originator service)
            "customerIdentification": "0x3E9181d09E56AdEF3bbc8BAb664Ce6B268Bf6e62", // Enum Code: 111006, Legal Person Customer Identification
            // required
            "countryOfRegistration": "HK" // Enum Code: 111022, ISO-3166-1 alpha-2 codes
          }
        },
        // required both legalPerson (ex: CEO name) and naturalPerson
        {
          // example fields below, please refer to above naturalPerson structure
          "naturalPerson": {
            // required
            "dateAndPlaceOfBirth": {
              "placeOfBirth": "US", // Enum Code: 110024, Natural Person Place of Birth
              "dateOfBirth": "1986-11-21" // Enum Code: 110025, Natural Person Date of Birth
            },
            // required
            "name": {
              "localNameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "サトシ",
                  "secondaryIdentifier": "ナカモト"
                }
              ], // Enum Code: 110027, Natural Person Local Name
              "nameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "Satoshi",
                  "secondaryIdentifier": "Nakamoto"
                }
              ] // Enum Code: 110026, Natural Person Name
            },
            // optional
            "geographicAddress": [
              {
                "addressType": "GEOG", // HOME, BIZZ, GEOG
                "streetName": "Potential Street", // Enum Code: 110034, Natural Person Address - Street
                "buildingNumber": "123", // Enum Code: 110035, Natural Person Address - Building Number
                "buildingName": "Cheese Hut", // Enum Code: 110036, Natural Person Address - Building Name
                "postCode": "91361", // Enum Code: 110040, Natural Person Address - Post Code
                "townName": "Thousand Oaks", // Enum Code: 110030, Natural Person Address - Town Name
                "countrySubDivision": "California", // Enum Code: 110043, Natural Person Address - Country of Sub Division
                "country": "US" // Enum Code: 110029, Natural Person Address - Country
              }
            ],
            // optional
            "nationalIdentification": {
              "nationalIdentifier": "1032903940290499SDF3-40DA024", // Enum Code: 110045, Natural Person National ID
              "nationalIdentifierType": "CCPT", // Enum Code: 110044, Natural Person National ID - Type
              "countryOfIssue": "HK" // Enum Code: 110046, Natural Person National ID - Country Of Issue
            },
            // optional, CUSTOMIZED FIELD (not IVMS101 standard): every identity document, one fixed slot each
            // slot key is ID_<nationalIdentifierType>; see section: About Field - specificNationalIdentifications
            "specificNationalIdentifications": {
              // mirrors the nationalIdentification above, same four IVMS101 values
              "ID_CCPT": {
                "nationalIdentifier": "1032903940290499SDF3-40DA024", // Enum Code: 110062, Natural Person National ID - passport number
                "nationalIdentifierType": "CCPT", // must equal the type in the slot key
                "countryOfIssue": "HK",
                // customized fields, optional, ISO 8601 date (YYYY-MM-DD), no Enum Code assigned
                "dateOfIssue": "2021-11-30",
                "dateOfExpiry": "2031-11-29"
              },
              // a national ID card that does not expire: fill dateOfIssue only, omit dateOfExpiry
              "ID_IDCD": {
                "nationalIdentifier": "A123456789", // Enum Code: 110068, Natural Person National ID - Identity card number assigned by a state agency
                "nationalIdentifierType": "IDCD",
                "countryOfIssue": "TW",
                "dateOfIssue": "2019-04-08"
              }
            },
            // required
            "customerIdentification": "10929392485393", // Enum Code: 110047, Natural Person Customer ID
            // required
            "countryOfResidence": "US" // Enum Code: 110048, Natural Person Country of Residence
          }
        }
      ],
      "accountNumber": ["1GURHee2JsCkdpxVisjbjAeNhbDbGub8R4"] // Enum Code: 113023, Account Number
    }
  }
}

Parameters Description

The nameIdentifierType is commonly set to 'LEGL'.
primaryIdentifier is lastName, secondaryIdentifier is firstName.
For primaryIdentifier, secondaryIdentifier. If the name cannot be separated, please fill firstName and lastName together (1. firstName 2. lastName).
firstName: givenName, lastName: familyName.
For the current version of IVMS specification, only the root level has first capital naming (e.g: Beneficiary, BeneficiaryVASP, Originator, OriginatingVASP).

Name Filling: the primary / secondary split is a convention, not a guarantee

The rules above describe how a sender should fill the name fields. They do not describe what a receiver will actually get, and the two must not be confused when you write matching code.

primaryIdentifier and secondaryIdentifier are populated inconsistently across jurisdictions, KYC vendors and VASP implementations, and the payload carries no signal saying which convention was used. In production you will receive all of the following for the same person:

`primaryIdentifier`	`secondaryIdentifier`	Why
`Nakamoto`	`Satoshi`	family name first, the IVMS101 convention
`Satoshi`	`Nakamoto`	the opposite convention, equally common in practice
`Satoshi Nakamoto`	(empty)	KYC record has no split, filled per the rule above
`Nakamoto Satoshi`	`Nakamoto Satoshi`	both fields filled with the full name
`サトシ`	`ナカモト`	a local name whose source system never had separate fields

As a sender:

Follow the convention: family name (plus middle name) in primaryIdentifier, given name in secondaryIdentifier.
If your KYC record cannot split the name, put the whole name in primaryIdentifier and leave secondaryIdentifier as an empty string. Do not guess a split, and do not fill null or undefined.
nameIdentifier is an array of up to 16 elements. If more than one reading of the name is plausible, send each as its own element rather than picking one.

As a receiver:

Do not rely on which role each field carries. Treat the pair as an unordered set of name parts.
At minimum, normalize both values (lower case, remove whitespace and special characters) and compare both orderings — primaryIdentifier + secondaryIdentifier and secondaryIdentifier + primaryIdentifier — plus each field on its own, and flag MATCHED if any of them matches any name you hold for the customer.
Apply the same handling to localNameIdentifier and phoneticNameIdentifier, and to every element of the array, not only [0].

A receiver that concatenates in one fixed order and compares will return false MISMATCH on names that were transmitted correctly. The exact candidate set, the normalization pattern and a reference implementation are in PII Matching Methods - NAME_FUZZY_VD.

In addition:

registrationAuthority

registrationAuthority is GLEIF code that you could find in GLEIF list: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list
registrationAuthority available for legalPerson, but the identity approved by immigration affairs is government department, not legal person.

nameIdentifierType (naturalPersonNameType)

ALIA (Alias name): A name other than the legal name by which a natural person is also known.
BIRT (Name at birth): The name given to a natural person at birth.
MAID (Maiden name): The original name of a natural person who has changed their name after marriage.
LEGL (Legal name): The name that identifies a natural person for legal, official or administrative purposes.
MISC (Unspecified): A name by which a natural person may be known but which cannot otherwise be categorized or the category of which the sender is unable to determine.

legalPersonNameIdentifierType (legalPersonNameType)

LEGL (Legal name): Official name under which an organisation is registered.
SHRT (Short name): Specifies the short name of the organisation.
TRAD (Trading name): Name used by a business for commercial purposes, although its registered legal name, used for contracts and other formal situations, may be another.

nationalIdentifierType

ARNU: Alien registration number (a number issued by the government to foreigners to identify them)
CCPT: passport number
RAID: (body corporate only) Business registration number provided by the authority
DRLC: Driver's License Number
FIIN: Foreign Investor Number (number assigned to foreign investors)
TXID: Number given by the tax authority
SOCS: Social Security Number or National Identification Number
IDCD: Identity card number assigned by a state agency
LEIX: (Legal entities only) Global legal entity identification number, LEI code assigned in accordance with the ISO 17442 standard
MISC: ID card number from other countries

Others

Other fields for more over,these are not necessary for the payloads:

localNameIdentifier: for non-English name of identity person, full name separated into primary and secondary identifier using local characters.

{
  "primaryIdentifier": "김",
  "secondaryIdentifier": "김지수",
  "nameIdentifierType": "LEGL" // IVMS101: ALIA, BIRT, MAID, LEGL, MISC
}

phoneticNameIdentifier: Alternate representation of a name that corresponds to the manner the name is pronounced.

{
  "primaryIdentifier": "Kim",
  "secondaryIdentifier": "Jisoo",
  "nameIdentifierType": "LEGL" // IVMS101: ALIA, BIRT, MAID, LEGL, MISC
}

transferPath (IntermediaryVasp): The transfer path refers to the intermediary VASP(s) participating in a serial chain that receive(s) and retransmit(s) a VA transfer on behalf of the originating VASP and the beneficiary VASP, or another intermediary VASP, together with their corresponding sequence number.
```
{
  "transferPath": [
    // IntermediaryVasp
    {
      "intermediaryVasp": {
        // legalPerson of vasp },
        "sequence": 0 // count from 0 to 9007199254740991L
      }
    }
  ]
}
```
payloadMetadata (TransliterationMethodCode): Data describing the contents of the payload. TransliterationMethodCode is the method used to map from a national system of writing to Latin script.
```
{
  "payloadMetadata": [
    "kore" // ISO 15924, arab, aran, armn, cyrl, deva, geor, grek, hani, hebr, kana, kore, thai, othr
  ]
}
```

For ISO 15924, the available enum is: arab, aran, armn, cyrl, deva, geor, grek, hani, hebr, kana, kore, thai, othr.

arab, Arabic (Arabic language) ISO 233-2:1993
aran, Arabic (Persian language) ISO 233-3:1999
armn, Armenian ISO 9985:1996
cyrl, Cyrillic ISO 9:1995
deva, Devanagari & related Indic ISO 15919:2001
geor, Georgian ISO 9984:1996
grek, Greek ISO 843:1997
hani, Han (Hanzi, Kanji, Hanja) ISO 7098:2015
hebr, Hebrew ISO 259-2:1994
kana, Kana ISO 3602:1989
kore, Korean Revised Romanization of Korean
thai, Thai ISO 11940-2:2007
othr, Script other than those listed above Unspecified

For example: 한국어 (hangug-eo), the method is "kore".

IVMS-101 Format Guidelines

Overview​

The necessary part to pre-fill in the JSON​

Necessary json-key preset in JSON by default​

About Field - Originator, Beneficiary​

About Field - OriginatingVASP​

About Field - BeneficiaryVASP​

About Field - TransferPath and Broker Account (IntermediaryVasp)​

Background​

Usage 1 - Broker Account behind Initiator VASP​

Usage 2 - Broker Account behind Receiver VASP​

Usage 3 - Initiator VASP Wants to Know if Broker Account behind Receiver VASP​

Usage 4 - Receiver VASP Wants to Know if Broker Account behind Initiator VASP​

travelRuleMetadata Fields Reference​

Rules to Fill IVMS​

All Required fields​

Example - Natural Person​

Example - Legal Person​

About Field - specificNationalIdentifications (Multiple ID Documents)​

Slot value fields​

Why fixed keys instead of an array​

Slot keys​

Rules​

Example - Natural Person with two documents​

Example - Legal Person with two documents​

Default Key-Value of IVMS​

For Natural Person Default​

For Legal Person Default​

Full Example of IVMS​

Parameters Description​

Name Filling: the primary / secondary split is a convention, not a guarantee​