Version: 4.6

Services

The Harmoney API-gateway OpenAPI specification contains all the available Harmoney services.

Below, you can find additional information and examples about the services that are provided.

Dossier services

PUT Dossier

This API-gateway service call creates or updates a dossier for a front-office. A back-office can also initiate a dossier for a front-office. Both offices exist in MyHarmoney and have fixed unique identifiers.
The dossier will only be created/updated if the user is authorized to do so for the provided front office.

Additional information:

When mandatory fields are not provided, the request will not be valid.
When parties are created, they must have one and only one type-specific property (e.g., individual, company, …)
When the dossier identifier is not known in the system, the dossier will be created.
When the dossier identifier is known in the system, the dossier will be updated and the previous state is overwritten.
When the party is already known in the system (based on the identifier), the provided party data will be updated.

HTTP Request


Method	PUT
URL	../financial-sps/{front-office-identifier}/dossiers/{dossier-identifier}
URL (for back-office)	../back-offices/{back-office-identifier}/dossiers/{dossier-identifier}

Request Body examples

Individual - Type KYC - via Back Office

{
  "frontOffice": {
    "identifier": "front-office-identifier"
  },
  "dossier": {
    "externalIdentifier": "identifier",
    "number": "uniqueNumber",
    "name": "dossier name",
    "type": "KNOW_YOUR_CUSTOMER",
    "service": "KNOW_YOUR_CUSTOMER",
    "client": {
      "externalIdentifier": "person_00001"
    },
    "externalInfo": {
      "source": "CRM",
      "metadata": {}
    }
  },
  "associatedParties": [
    {
      "externalIdentifier": "person_00001",
      "individual": {
        "firstName": "john",
        "lastName": "doe",
        "dateOfBirth": "1999-12-31"
      },
      "externalInfo": {
        "metadata": {
          "METADATA_RISK": "High",
          "METADATA_RELATION": "Medium"
        }
      }
    }
  ]
}

Individual - Type Insurance - via Front Office

{
  "dossier": {
    "externalIdentifier": "identifier",
    "number": "uniqueNumber",
    "name": "dossier name",
    "type": "INSURANCE",
    "service": "SAVINGS_INVESTMENT_INSURANCE",
    "client": {
      "externalIdentifier": "person_00001"
    },
    "insurance": {
      "paymentPeriodicity": "ONE_TIME",
      "premium": "1000.00",
      "balance": "1000.00",
      "balanceDate": "2020-07-16",
      "iban": "BE12999293718292",
      "insurees": [
        {
          "externalIdentifier": "person_00001"
        }
      ]
    }
  },
  "associatedParties": [
    {
      "externalIdentifier": "person_00001",
      "individual": {
        "firstName": "john",
        "lastName": "doe",
        "dateOfBirth": "1999-12-31",
        "placeOfBirth": "Gent",
        "nationality": "BE",
        "additionalNationalities": [
          "NL",
          "FR"
        ],
        "gender": "MALE",
        "mobilePhone": "+32456123789",
        "email": "[email protected]",
        "maritalStatus": "SINGLE",
        "maritalStatusSince": "1999-12-31",
        "language": "NL",
        "occupation": "Homeless",
        "socialState": "WORKER",
        "education": "COLLEGE",
        "industrySector": "CHARITY",
        "dependentChildren": "2",
        "partnerName": "Jane ",
        "iban": "BE16557449113474",
        "nationalRegistrationNumber": "99123100077",
        "identityCardNumber": "555999999944",
        "identityCardValidTo": "2050-12-31",
        "address": {
          "fullStreet": "Central Park 9/A",
          "postalCode": "1234",
          "city": "Some Town",
          "country": "BE"
        },
        "identityDocuments": [
          {
            "name": "scan id card",
            "type": "FRONT_BACK_SCAN",
            "file": {
              "filename": "scan_id_card.pdf",
              "mimeType": "application/pdf",
              "content": "iVBORw0KGgoAAAJggg=="
            }
          }
        ]
      }
    }
  ]
}

Company - Type Investment - via Front Office

{
  "dossier": {
    "externalIdentifier": "identifier",
    "number": "uniqueNumber",
    "name": "dossier name",
    "type": "INVESTMENT",
    "service": "DISCRETIONARY",
    "client": {
      "externalIdentifier": "company_00001"
    },
    "investment": {
      "accounts": [
        {
          "externalAccountNumber": "Account number 1",
          "assetName": "Account name 1",
          "assetValue": "15000.00",
          "assetValueDate": "2019-01-01"
        }
      ]
    }
  },
  "associatedParties": [
    {
      "externalIdentifier": "company_00001",
      "company": {
        "name": "Gemaflor",
        "companyNumber": "0433357396",
        "address": {
          "country": "BE"
        },
        "owners": [
          {
            "externalIdentifier": "person_00001",
            "percentage": "100",
            "uboType": "OWNERSHIP"
          }
        ]
      }
    },
    {
      "externalIdentifier": "person_00001",
      "individual": {
        "firstName": "john",
        "lastName": "doe",
        "dateOfBirth": "1999-12-31"
      }
    }
  ]
}

Indivision - Type KYC

{
  "dossier": {
    "externalIdentifier": "identifier",
    "number": "uniqueNumber",
    "name": "dossier name",
    "type": "KNOW_YOUR_CUSTOMER",
    "service": "KNOW_YOUR_CUSTOMER",
    "client": {
      "externalIdentifier": "indivision_00001"
    }
  },
  "associatedParties": [
    {
      "externalIdentifier": "indivision_00001",
      "indivision": {
        "name": "indivision name",
        "members": [
          {
            "externalIdentifier": "person_00001",
            "percentage": "50"
          },
          {
            "externalIdentifier": "person_00002",
            "percentage": "50"
          }
        ]
      }
    },
    {
      "externalIdentifier": "person_00001",
      "individual": {
        "firstName": "john",
        "lastName": "doe",
        "dateOfBirth": "1999-12-31"
      }
    },
    {
      "externalIdentifier": "person_00002",
      "individual": {
        "firstName": "jane",
        "lastName": "doe",
        "dateOfBirth": "1999-11-30"
      }
    }
  ]
}

Example with related dossiers & parties and tax information on a party

{
  "dossier": {
    "externalIdentifier": "identifier",
    "number": "uniqueNumber",
    "name": "dossier name",
    "type": "KNOW_YOUR_CUSTOMER",
    "service": "KNOW_YOUR_CUSTOMER",
    "client": {
      "externalIdentifier": "person_00001"
    },
    "relatedParties": [
      {
        "identifier": {
          "externalIdentifier": "person_00002"
        },
        "relationType": "OTHER"
      }
    ],
    "relatedDossiers": [
      {
        "externalIdentifier": "dossier_x_1"
      }
    ]
  },
  "associatedParties": [
    {
      "externalIdentifier": "person_00001",
      "individual": {
        "firstName": "john",
        "lastName": "doe",
        "dateOfBirth": "1999-12-31",
        "address": {
          "fullStreet": "Korenmarkt",
          "postalCode": "9000",
          "city": "Gent",
          "country": "BE"
        }
      },
      "relatedParties": [
        {
          "identifier": {
            "externalIdentifier": "person_00002"
          },
          "relationType": "OTHER"
        }
      ],
      "taxInformations": [
        {
          "tin": "12345678901",
          "isPrimary": true,
          "useResidentialAddress": true
        },
        {
          "tin": "12345678999",
          "isPrimary": false,
          "useResidentialAddress": false,
          "address": {
            "fullStreet": "Groenplaats",
            "postalCode": "2000",
            "city": "Antwerp",
            "country": "BE"
          }
        }
      ]
    },
    {
      "externalIdentifier": "person_00002",
      "individual": {
        "firstName": "jane",
        "lastName": "doe",
        "dateOfBirth": "1999-11-30"
      }
    }
  ]
}

Example with an intermediary on the dossier

{
  "dossier": {
    "externalIdentifier": "identifier",
    "number": "uniqueNumber",
    "name": "dossier name",
    "type": "KNOW_YOUR_CUSTOMER",
    "service": "KNOW_YOUR_CUSTOMER",
    "client": {
      "externalIdentifier": "indivision_00001"
    },
    "intermediary": {
      "identifier": "frontoffice_reference"
    }
  },
  "associatedParties": [
    {
      "externalIdentifier": "indivision_00001",
      "indivision": {
        "name": "indivision name",
        "members": [
          {
            "externalIdentifier": "person_00001",
            "percentage": "50"
          }
        ]
      }
    },
    {
      "externalIdentifier": "person_00001",
      "individual": {
        "firstName": "john",
        "lastName": "doe",
        "dateOfBirth": "1999-12-31"
      }
    }
  ]
}

POST Flow

This API-gateway service call performs the necessary actions to initiate the flow for a specific responsible on a dossier, by identifying the Dossier and Responsible within the context of a front-office. Depending on the configuration, one or several flow-options are possible. For each responsible on the dossier, the flow call must be executed separately to complete the Dossier, so the Dossier can be submitted to the front office.

Additional information:

The configured flow-options need to be communicated by Harmoney.
The front-office linked to the dossier must have the Investor flow module enabled.

Flow-options:

Flow option	Description
`GENERATE_CODE`	A CODE is created that should be used by the Responsible to start the correct Flow for a specific Dossier in Harmoney, using the dedicated landing-page on Harmoney indicated by the URL field.
`GENERATE_URL`	An absolute URL is created that should be used by the Responsible to directly start the correct Flow for a specific Dossier in Harmoney.
`DIRECT_INVESTOR_MAIL`	Send a mail inviting the responsible to complete the flow. The responsible will start directly with the flow. The responsible is required to have a valid e-mail.
`INVESTOR_MAIL`	Send a mail inviting the responsible to complete the flow. The responsible will have to login or register before they can start with the flow.The responsible is required to have a valid e-mail.

Response examples

flowOption: GENERATE_CODE

{
  "url": "https://<whitelabel>.myharmoney.eu/shorturl/",
  "code": "AZERTY"
}

flowOption: GENERATE_URL

{
  "url": "https://<whitelabel>.myharmoney.eu/token?token=<tokenId>&idLang=<langId>"
}

flowOption: DIRECT_INVESTOR_MAIL

{}

GET Dossier

Use this API-gateway service call to retrieve a dossier from a front-office or a back-office. Based on the provided query params, more or less data will be added to the response. There are 2 options, either provide the expanded param that is true (everything is included) or false (minimal data is provided). To have a more controlled way to determine which data should be included, the includes param can be used. An overview of the includes options is available in the Gateway OpenAPI docs. Combining the query parameters is not possible.

HTTP Request


Method	GET
URL	../financial-sps/{front-office-identifier}/dossiers/{dossier-identifier}
URL (for back-office)	../back-offices/{back-office-identifier}/dossiers/{dossier-identifier}

Request body examples

../financial-sps/front-office-identifier/dossiers/dossierExternalIdentifier?expanded=false

{
  "frontOffice": {
    "identifier": "front-office-identifier"
  },
  "dossier": {
    "externalIdentifier": "dossierExternalIdentifier",
    "internalIdentifier": "HhpTts9Qj/0gyhy+SnDLXQ==",
    "number": "uniqueNumber",
    "name": "name",
    "type": "KNOW_YOUR_CUSTOMER",
    "service": "KNOW_YOUR_CUSTOMER",
    "client": {
      "externalIdentifier": "company_00001"
    }
  },
  "associatedParties": []
}

../financial-sps/front-office-identifier/dossiers/dossierExternalIdentifier?expanded=true

{
  "frontOffice": {
    "identifier": "front-office-identifier"
  },
  "dossier": {
    "externalIdentifier": "identifier",
    "internalIdentifier": "HhpTts9Qj/0gyhy+SnDLXQ==",
    "client": {
      "externalIdentifier": "person_00001"
    },
    "number": "uniqueNumber",
    "name": "name",
    "type": "KNOW_YOUR_CUSTOMER",
    "service": "KNOW_YOUR_CUSTOMER",
    "commercialProduct": {
      "externalReference": "commercial_product_ref"
    },
    "status": "APPROVED",
    "rba": {
      "rating": "HIGH",
      "timeUpdated": "2018-12-12T15:16:46Z",
      "score": "70",
      "escalation": "false",
      "productFactor": "1",
      "systemAssessment": "NOK",
      "details": [
        {
          "parameter": "PEP",
          "result": "YES",
          "score": "70"
        }
      ]
    },
    "metadata": {},
    "documents": [
      {
        "name": "doc name",
        "type": "DOC_TYPE",
        "filename": "file-name.pdf",
        "contentURL": "https://cdn.myharmoney.eu/…",
        "timeUpdated": "2020-10-02T15:18:44Z"
      }
    ],
    "externalInfo": {
      "source": "CRM",
      "metadata": {}
    }
  },
  "associatedParties": [
    {
      "externalIdentifier": "person_00001",
      "internalIdentifier": "HhpTts9Qj/0gyhy+SnDLXQ==",
      "individual": {
        "firstName": "john",
        "lastName": "doe",
        "nationality": "BE",
        "nationalRegistrationNumber": "99123100077",
        "mobilePhone": "+32456123789",
        "gender": "MALE",
        "email": "[email protected]",
        "dateOfBirth": "1999-12-31",
        "language": "NL",
        "maritalStatus": "SINGLE",
        "address": {
          "fullStreet": "Central Park 9/A",
          "postalCode": "1234",
          "city": "OldTown",
          "country": "BE"
        },
        "identityDocuments": []
      },
      "metadata": {},
      "externalInfo": {
        "metadata": {
          "METADATA_RISK": "High",
          "METADATA_RELATION": "Medium"
        }
      }
    }
  ]
}

../financial-sps/front-office-identifier/dossiers/dossierExternalIdentifier?includes=["CLIENT"]

{
  "frontOffice": {
    "identifier": "front-office-identifier"
  },
  "dossier": {
    "externalIdentifier": "dossierExternalIdentifier",
    "internalIdentifier": "HhpTts9Qj/0gyhy+SnDLXQ==",
    "number": "uniqueNumber",
    "name": "name",
    "type": "KNOW_YOUR_CUSTOMER",
    "service": "KNOW_YOUR_CUSTOMER",
    "status": "APPROVED",
    "lifecycle": "ONBOARDING",
    "client": {
      "externalIdentifier": "company_00001"
    },
    "metadata": {}
  },
  "associatedParties": [
    {
      "externalIdentifier": "company_00001",
      "internalIdentifier": "HhpTts9Qj/0gyhy+SnDLXQ=="
    }
  ]
}

GET Risk Analysis

This service can be used to retrieve the RBA (Risk Based Approach) results for an existing dossier (if available).
The front-office/back-office must have the RBA module enabled.

Response examples

{
  "rating": "HIGH",
  "timeUpdated": "2018-12-12T15:16:46Z",
  "score": 70,
  "escalation": "false",
  "productFactor": 1,
  "details": [
    {
      "parameter": "AML_MATCH",
      "result": "YES",
      "score": "70"
    }
  ]
}

GET Dossier Questionnaire Answers

This service can be used to retrieve the answers of questionnaires of a dossier.
Dossier questionnaires are only applicable when the Dossier Questionnaires module is active and when there are questionnaires configured for the dossier definition. The dossier questionnaires should not be confused with the questionnaires used in a flow (see flow-related endpoints for this).

For each questionnaire, only the questions are returned for which an answer has been provided.

Response examples

[
  {
    "questionnaireIdentifier": "customer_advisor_form_01",
    "answers": [
      {
        "questionIdentifier": "Q_HAS_PETS",
        "answer": true
      },
      {
        "questionIdentifier": "Q_PET_NAMES",
        "answer": "Woofy"
      },
      {
        "questionIdentifier": "Q_PET_FEATURES",
        "answer": [
          "1",
          "3"
        ]
      }
    ]
  },
  {
    "questionnaireIdentifier": "customer_advisor_form_02",
    "answers": []
  }
]

GET Dossier Answers

This service can be used to retrieve all the answers applicable for the dossier.
These can be questions that are asked via dossier questionnaires, but also questions who are asked on an information exchange flow (also known as the investor flow)

Response examples

[
  {
    "questionIdentifier": "Q_HAS_PETS",
    "answer": true
  },
  {
    "questionIdentifier": "Q_PET_NAMES",
    "answer": "Woofy"
  },
  {
    "questionIdentifier": "Q_PET_FEATURES",
    "answer": [
      "1",
      "3"
    ]
  }
]

Put Dossier Answers

This service can be used to update answers applicable for the dossier.
It’s advised to use the update strategy APPEND to avoid losing answers of questions who are not defined in the body of the message (see more details in the OpenApi spec).
The formatting of the answer depends on the answer type of the question.

Request body examples

[
  {
    "questionIdentifier": "Q_HAS_PETS",
    "answer": true
  },
  {
    "questionIdentifier": "Q_PET_NAMES",
    "answer": "Woofy"
  },
  {
    "questionIdentifier": "Q_PET_AGE",
    "answer": 13
  },
  {
    "questionIdentifier": "Q_PET_FEATURES",
    "answer": [
      "1",
      "3"
    ]
  }
]

GET Flow completion results

This service can be used to retrieve the results of the flow completion performed by the responsible person(s) of the dossier.
Retrieving the flow completion results using a front-office requires the Investor flow module to be enabled on that front-office.
Retrieving the flow completion results using a back-office requires the Investor results module to be enabled on that back-office.

Response examples

[
  {
    "status": "COMPLETED",
    "timeCompleted": "2020-01-01 22:22:22Z0",
    "flowDocuments": [
      {
        "partyIdentifier": {
          "externalIdentifier": "person_00001"
        },
        "documents": [
          {
            "type": "INVESTOR_FLOW",
            "url": "https://cdn.myharmoney.eu/…"
          }
        ]
      }
    ],
    "profiles": [
      {
        "partyIdentifier": null,
        "type": "INVESTMENT",
        "profile": "DYNAMIC",
        "score": 80
      }
    ]
  }
]

POST Flow completion results

This service can be used to create a flow completion result for a dossier. Creating a flow completion result requires the Investor flow module to be enabled on the front-office.
The creation of a flow completion result is only possible for dossiers that don’t already have existing flow completion results and is limited to one profile for each profile type.
Created flow completion results through this endpoint will always have the status EXTERNAL.

Request body examples

{
  "timeCompleted": "2024-01-24",
  "profiles": [
    {
      "type": "INVESTMENT",
      "profile": "DEFENSIVE"
    }
  ]
}

GET Flow completion questionnaire answers

This service can be used to retrieve all the answers of a flow completion performed by the responsible person(s) of the dossier.
Retrieving the flow completion results using a front-office requires the Investor flow module to be enabled on that front-office.
Retrieving the flow completion results using a back-office requires the Investor results module to be enabled on that back-office.

For each questionnaire, only the questions are returned for which an answer has been provided.

Response examples

[
  {
    "questionIdentifier": "Is_PEP",
    "answer": "1",
    "createdFor": {
      "externalIdentifier": "597076"
    }
  },
  {
    "questionIdentifier": "Is_PEP_since",
    "answer": "2020-01-01",
    "createdFor": {
      "externalIdentifier": "597076"
    }
  },
  {
    "questionIdentifier": "Is_PEP_still_active",
    "answer": "true",
    "createdFor": {
      "externalIdentifier": "597076"
    }
  }
]

Party services

GET Party

Use this API-gateway service call to retrieve a party from a front-office. Based on the provided query params, more or less data will be added to the response. There are 2 options, either provide the expanded param that is true (everything is included) or false (minimal data is provided). To have a more controlled way to determine which data should be included, the includes param can be used. An overview of the includes options is available in the Gateway OpenAPI docs. Combining the query parameters is not possible.

HTTP Request


Method	GET
URL	../financial-sps/{front-office-identifier}/parties/{party-identifier}

Response examples

../financial-sps/{front-office-identifier}/parties/{party-identifier}?expanded=false

{
  "party": {
    "externalIdentifier": "partyIdentifier",
    "internalIdentifier": "ePO4/F3aaxzFkTb+owGpBQ=="
  }
}

../financial-sps/{front-office-identifier}/parties/{party-identifier}?expanded=true

{
  "party": {
    "externalIdentifier": "partyIdentifier",
    "internalIdentifier": "ePO4/F3aaxzFkTb+owGpBQ==",
    "individual": {
      "firstName": "john",
      "lastName": "doe",
      "address": {
        "fullStreet": "Central Park 9/A",
        "postalCode": "1234",
        "city": "Gent",
        "country": "BE"
      }
    },
    "relatedParties": [
      {
        "identifier": {
          "externalIdentifier": "relatedPartyIdentifier",
          "internalIdentifier": "MBfdr31Odc+sgT/lZ08ebQ=="
        },
        "relationType": "CHILD"
      }
    ],
    "taxInformations": [
      {
        "tin": "12345678901",
        "isPrimary": true,
        "useResidentialAddress": true
      },
      {
        "tin": "12345678999",
        "isPrimary": false,
        "useResidentialAddress": false,
        "address": {
          "fullStreet": "Groenplaats",
          "postalCode": "2000",
          "city": "Antwerp",
          "country": "BE"
        }
      }
    ],
    "metadata": {
      "KEY": "value"
    },
    "externalInfo": {
      "metadata": {
        "METADATA_RISK": "High",
        "METADATA_RELATION": "Medium"
      }
    }
  },
  "associatedParties": [
    {
      "externalIdentifier": "relatedPartyIdentifier",
      "internalIdentifier": "MBfdr31Odc+sgT/lZ08ebQ==",
      "individual": {
        "firstName": "related",
        "lastName": "to john doe",
        "address": {
          "fullStreet": "Avenue 15",
          "postalCode": "2000",
          "city": "Antwerp",
          "country": "BE"
        }
      },
      "metadata": {}
    }
  ]
}

../financial-sps/{front-office-identifier}/parties/{party-identifier}?includes=[“PARTY_INFO”]

{
  "party": {
    "externalIdentifier": "partyIdentifier",
    "internalIdentifier": "ePO4/F3aaxzFkTb+owGpBQ==",
    "company": {
      "name": "ExampleCompany",
      "companyNumber": "0000000000",
      "address": {
        "fullStreet": null,
        "postalCode": null,
        "city": null,
        "country": null
      }
    },
    "metadata": {},
    "postalAddress": {
      "fullStreet": null,
      "postalCode": null,
      "city": null,
      "country": null
    }
  }
}

PUT party

This API-gateway service call creates or updates a party for a front-office.
The party will only be created/updated if the user is authorized to do so for the provided front office.

Additional information:

When mandatory fields are not provided, the request will not be valid.
When parties are created, they must have one and only one type-specific property (e.g., individual, company, …)
- Individual: An individual is a specific type of party which can only exist of 1, also known as a person.
  e.g. “Homer Simpsons” is a specific individual.
- Company: A company is a specific type of Party that forms a legal entity by a group of parties to engage in and operate a business -commercial or industrial- enterprise.
  e.g. “Homer Simpsons” works at the “Springfield Nuclear Power Plant” company.
- Indivision: An indivision is a specific type of party which can exist out of multiple persons.
  e.g., The family “The Simpsons” can be seen as an indivision.
- Partnership: A partnership is a company of common law.
When the party identifier is not known in the system, the party will be created.
When the party identifier is known in the system, the party will be updated and the previous state is overwritten.
When the party is already known in the system (based on the identifier), the provided party data will be updated.

Request Body examples

Individual

{
  "party": {
    "externalIdentifier": "partyIdentifier",
    "individual": {
      "firstName": "Homer",
      "lastName": "Simpson",
      "address": {
        "fullStreet": "Central Park 9/A",
        "postalCode": "1234",
        "city": "New York",
        "country": "US"
      }
    },
    "relatedParties": [
      {
        "identifier": {
          "externalIdentifier": "relatedPartyIdentifier"
        },
        "relationType": "CHILD"
      }
    ],
    "taxInformations": [
      {
        "tin": "12345678901",
        "isPrimary": true,
        "useResidentialAddress": true
      },
      {
        "tin": "12345678999",
        "isPrimary": false,
        "useResidentialAddress": false,
        "address": {
          "fullStreet": "Groenplaats",
          "postalCode": "2000",
          "city": "Antwerp",
          "country": "BE"
        }
      }
    ]
  },
  "associatedParties": [
    {
      "externalIdentifier": "relatedPartyIdentifier",
      "individual": {
        "firstName": "Marge",
        "lastName": "Simpson",
        "address": {
          "fullStreet": "Groenplaats 15",
          "postalCode": "2000",
          "city": "Antwerp",
          "country": "BE"
        }
      }
    }
  ]
}

Company

{
  "party": {
    "externalIdentifier": "partyIdentifier",
    "company": {
      "name": "Springfield Nuclear Power Plant",
      "companyNumber": "0405450102",
      "companyType": "PUBLICLY_LISTED",
      "nace": "C.12.0",
      "owners": [
        {
          "externalIdentifier": "ownerIdentifier",
          "percentage": 55.0,
          "uboType": "OWNERSHIP"
        }
      ],
      "address": {
        "country": "BE"
      }
    },
    "relatedParties": [
      {
        "identifier": {
          "externalIdentifier": "shareholder"
        },
        "relationType": "DIRECT_SHAREHOLDER",
        "directSharePercentage": 50.25,
        "totalSharePercentage": 50.25
      }
    ]
  },
  "associatedParties": [
    {
      "externalIdentifier": "shareholder",
      "individual": {
        "firstName": "share",
        "lastName": "holder",
        "address": {
          "country": "BE"
        }
      }
    },
    {
      "externalIdentifier": "ownerIdentifier",
      "individual": {
        "firstName": "Marge",
        "lastName": "Simposon",
        "address": {
          "country": "BE"
        }
      }
    }
  ]
}

Indivision

{
  "party": {
    "externalIdentifier": "partyIdentifier",
    "indivision": {
      "name": "Fund X",
      "members": [
        {
          "externalIdentifier": "ownerIdentifier",
          "percentage": 55.0,
          "uboType": "OWNERSHIP"
        }
      ],
      "bankAccounts": {
        "IBAN": "BE123456789012",
        "Name": "Name of IBAN"
      }
    },
    "relatedParties": [
      {
        "identifier": {
          "externalIdentifier": "shareholder"
        },
        "relationType": "Contact person",
        "directSharePercentage": 50.25,
        "totalSharePercentage": 50.25
      }
    ]
  },
  "associatedParties": [
    {
      "externalIdentifier": "shareholder",
      "individual": {
        "firstName": "Marge",
        "lastName": "Simpson",
        "address": {
          "country": "BE"
        }
      }
    },
    {
      "externalIdentifier": "ownerIdentifier",
      "individual": {
        "firstName": "Homer",
        "lastName": "Simpson",
        "address": {
          "country": "BE"
        }
      }
    }
  ]
}

Partnership

{
  "party": {
    "externalIdentifier": "partyIdentifier",
    "partnership": {
      "name": "Example partnership",
      "members": [
        {
          "externalIdentifier": "ownerIdentifier",
          "percentage": 55.0
        }
      ],
      "bankAccounts": {
        "IBAN": "BE123456789012",
        "name": "Example"
      }
    },
    "relatedParties": [
      {
        "identifier": {
          "externalIdentifier": "shareholder"
        },
        "relationType": "Contact person",
        "directSharePercentage": 50.25,
        "totalSharePercentage": 100
      }
    ]
  }
}

GET Party Answers

This service can be used to retrieve all the answers applicable for the party.
These can be questions that are asked via dossier information exchange flow (also known as the investor flow) from a linked dossier.

Response examples

[
  {
    "questionIdentifier": "Q_HAS_PETS",
    "answer": true
  },
  {
    "questionIdentifier": "Q_PET_NAMES",
    "answer": "Woofy"
  },
  {
    "questionIdentifier": "Q_PET_FEATURES",
    "answer": [
      "1",
      "3"
    ]
  }
]

Put Party Answers

This service can be used to update answers applicable for the party.
It’s advised to use the update strategy APPEND to avoid losing answers of questions who are not defined in the body of the message (see more details in the OpenApi spec).
The formatting of the answer depends on the answer type of the question.

Request body examples

[
  {
    "questionIdentifier": "Q_HAS_PETS",
    "answer": true
  },
  {
    "questionIdentifier": "Q_PET_NAMES",
    "answer": "Woofy"
  },
  {
    "questionIdentifier": "Q_PET_AGE",
    "answer": 13
  },
  {
    "questionIdentifier": "Q_PET_FEATURES",
    "answer": [
      "1",
      "3"
    ]
  }
]

Information Exchanges

An Information Exchange is a request for information sent to a counterparty of a dossier (for example an individual investor or an intermediary). It is the API-gateway equivalent of the investor flow, but it is addressed to a specific counterparty and it keeps track of the collected answers, generated profiles and produced documents for that counterparty.

These services allow you to create Information Exchanges on a dossier, initiate them (so the counterparty can complete them), retrieve their results and cancel them again.

Additional information:

The financial service provider linked to the dossier must have the Information exchange module enabled.
Each Information Exchange is identified by a informationExchangeIdentifier. This identifier is returned when the Information Exchange is created and is used as a path parameter in the subsequent calls.

An Information Exchange is created for a single counterparty, identified by its type and its identifier:

Counterparty type	Description
`INDIVIDUAL`	An individual party (e.g. the investor), referenced by its party identifier.
`INTERMEDIARY`	An intermediary financial service provider, referenced by its external reference.

The status of an Information Exchange reflects its progress. The possible statuses are CREATED, PENDING (awaiting completion), COMPLETED, CANCELLED and EXTERNAL (created through the external completion service).

All Information Exchange services share the following base URL:


Base	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges

Retrieving Information Exchange data from a dossier

Retrieve all Information Exchanges from a dossier

This service retrieves all Information Exchanges of a dossier, sorted by their creation time. For a completed Information Exchange, the generated profiles and produced documents are included as well.

HTTP Request


Method	GET
URL	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges

Response examples

[
  {
    "informationExchangeIdentifier": "31234",
    "status": "PENDING",
    "counterpartyType": "INTERMEDIARY",
    "counterparty": {
      "externalIdentifier": "ext_ref_intermediary"
    },
    "timeCreated": "2026-07-01T09:30:00Z",
    "timeUpdated": "2026-07-01T09:30:00Z"
  },
  {
    "informationExchangeIdentifier": "31555",
    "status": "COMPLETED",
    "counterpartyType": "INDIVIDUAL",
    "counterparty": {
      "externalIdentifier": "person_00001"
    },
    "timeCreated": "2026-06-20T08:00:00Z",
    "timeUpdated": "2026-06-21T14:10:00Z",
    "profiles": [
      {
        "type": "INVESTMENT",
        "profile": "DYNAMIC",
        "score": 80
      }
    ],
    "documents": [
      {
        "counterpartyType": "INDIVIDUAL",
        "counterparty": {
          "externalIdentifier": "person_00001"
        },
        "documents": [
          {
            "type": "PROOF_OF_FUNDS",
            "contentUrl": "https://cdn.myharmoney.eu/…"
          }
        ]
      }
    ]
  }
]

Retrieve a specific Information Exchange from a dossier

This service retrieves a single Information Exchange of a dossier, based on its identifier. The documents are grouped by counterparty. Each group contains the documents produced for one counterparty (an individual or an intermediary).

HTTP Request


Method	GET
URL	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges/{information-exchange-identifier}

Response examples

{
  "informationExchangeIdentifier": "31555",
  "status": "COMPLETED",
  "counterpartyType": "INTERMEDIARY",
  "counterparty": {
    "externalIdentifier": "ext_ref_intermediary"
  },
  "timeCreated": "2026-06-20T08:00:00Z",
  "timeUpdated": "2026-06-21T14:10:00Z",
  "profiles": [
    {
      "type": "INVESTMENT",
      "profile": "DYNAMIC",
      "score": 80
    }
  ],
  "documents": [
    {
      "counterpartyType": "INDIVIDUAL",
      "counterparty": {
        "externalIdentifier": "person_00001"
      },
      "documents": [
        {
          "type": "BANK_VERIFICATION",
          "contentUrl": "https://cdn.myharmoney.eu/…"
        }
      ]
    },
    {
      "counterpartyType": "INTERMEDIARY",
      "counterparty": {
        "externalIdentifier": "ext_ref_intermediary"
      },
      "documents": [
        {
          "type": "ORIGIN_OF_FUNDS",
          "contentUrl": "https://cdn.myharmoney.eu/…"
        }
      ]
    }
  ]
}

Retrieve questionnaire answers from a specific Information Exchange

This service retrieves all the questionnaire answers that were collected for a specific Information Exchange. Only the questions for which an answer has been provided are returned. The createdFor field indicates the party the answer relates to.

HTTP Request


Method	GET
URL	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges/{information-exchange-identifier}/questionnaire/answers

Response examples

[
  {
    "questionIdentifier": "Is_PEP",
    "answer": "1",
    "createdFor": {
      "externalIdentifier": "person_00001"
    }
  },
  {
    "questionIdentifier": "Is_PEP_since",
    "answer": "2020-01-01",
    "createdFor": {
      "externalIdentifier": "person_00001"
    }
  }
]

Create a new Information Exchange

This service creates a new Information Exchange on a dossier for a given counterparty. The counterparty is resolved from the counterpartyType and counterpartyIdentifier provided in the request body.

Additional information:

When a CREATED or PENDING Information Exchange already exists for the same counterparty, that one is returned as-is instead of creating a new one.
When the counterparty cannot be resolved, the request results in a 404.
Before the Information Exchange is created, a creatability check is run. When it does not pass, the request results in a 400. This check requires all of the following:
- The dossier definition supports an Information Exchange for the requested counterparty type (a flow configuration is set up for it); for an INTERMEDIARY counterparty the Intermediary module must also be enabled.
- The current user is allowed to update the dossier, and the dossier is in a state that still allows updates.
- The dossier is in a status from which an Information Exchange may be started.
- The dossier has no other pending Information Exchange, as a new one cannot be created while another is still open.
The created Information Exchange has status CREATED. To let the counterparty complete it, it still needs to be initiated.

HTTP Request


Method	POST
URL	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges

Request body examples

{
  "counterpartyType": "INTERMEDIARY",
  "counterpartyIdentifier": "ext_ref_intermediary"
}

Response examples

{
  "informationExchangeIdentifier": "31234",
  "status": "CREATED",
  "counterpartyType": "INTERMEDIARY",
  "counterparty": {
    "externalIdentifier": "ext_ref_intermediary"
  },
  "timeCreated": "2026-07-08T09:30:00Z",
  "timeUpdated": "2026-07-08T09:30:00Z"
}

Initiate a new Information Exchange

This service initiates a pending Information Exchange by selecting a flow option. Initiating the Information Exchange returns the URL and/or code that the counterparty can use to complete it.

Additional information:

Only a CREATED or PENDING Information Exchange that is the current one on the dossier can be initiated.
The available flow options depend on the dossier configuration (set up on the Harmoney admin side) and on the counterparty type of the Information Exchange:
- For an INDIVIDUAL counterparty the possible values are GENERATE_CODE, GENERATE_URL and DIRECT_INVESTOR_MAIL.
- For an INTERMEDIARY counterparty the options are restricted to GENERATE_URL and DIRECT_INVESTOR_MAIL.
When a flow option that is not allowed for the Information Exchange is selected, the request is rejected.

HTTP Request


Method	POST
URL	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges/{information-exchange-identifier}/initiate

Request body examples

{
  "flowOption": "GENERATE_URL"
}

Response examples

flowOption: GENERATE_URL

{
  "url": "https://<whitelabel>.myharmoney.eu/token?token=<tokenId>&idLang=<langId>"
}

flowOption: DIRECT_INVESTOR_MAIL

{}

Cancel an open Information Exchange

This service cancels an ongoing (pending) Information Exchange. After cancellation the Information Exchange can no longer be completed by the counterparty.

HTTP Request


Method	DELETE
URL	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges/{information-exchange-identifier}

A successful cancellation returns a 204 No Content response.

Create an external Information Exchange completion

This service posts an Information Exchange that was completed outside of Harmoney to a dossier. It is used to register the results (profiles and, optionally, documents) of an externally executed information exchange.

Additional information:

The timeCompleted field is required.
Information Exchanges created through this service always get the status EXTERNAL.

HTTP Request


Method	POST
URL	../financial-sps/{financial-service-provider-identifier}/dossiers/{dossier-identifier}/information-exchanges/completions

Request body examples

{
  "timeCompleted": "2026-07-08T09:30:00Z",
  "profiles": [
    {
      "type": "INVESTMENT",
      "profile": "DEFENSIVE"
    }
  ]
}

A successful call returns a 204 No Content response.

Dossier services​

PUT Dossier​

HTTP Request​

Request Body examples​

POST Flow​

Response examples​

GET Dossier​

HTTP Request​

Request body examples​

GET Risk Analysis​

Response examples​

GET Dossier Questionnaire Answers​

Response examples​

GET Dossier Answers​

Response examples​

Put Dossier Answers​

Request body examples​

GET Flow completion results​

Response examples​

POST Flow completion results​

Request body examples​

GET Flow completion questionnaire answers​

Response examples​

Party services​

GET Party​

HTTP Request​

Response examples​

PUT party​

Request Body examples​

GET Party Answers​

Response examples​

Put Party Answers​

Request body examples​

Information Exchanges​

Retrieving Information Exchange data from a dossier​

Retrieve all Information Exchanges from a dossier​

HTTP Request​

Response examples​

Retrieve a specific Information Exchange from a dossier​

HTTP Request​

Response examples​

Retrieve questionnaire answers from a specific Information Exchange​

HTTP Request​

Response examples​

Create a new Information Exchange​

HTTP Request​

Request body examples​

Response examples​

Initiate a new Information Exchange​

HTTP Request​

Request body examples​

Response examples​

Cancel an open Information Exchange​

HTTP Request​

Create an external Information Exchange completion​

HTTP Request​

Request body examples​

Dossier services

PUT Dossier

HTTP Request

Request Body examples

POST Flow

Response examples

GET Dossier

HTTP Request

Request body examples

GET Risk Analysis

Response examples

GET Dossier Questionnaire Answers

Response examples

GET Dossier Answers

Response examples

Put Dossier Answers

Request body examples

GET Flow completion results

Response examples

POST Flow completion results

Request body examples

GET Flow completion questionnaire answers

Response examples

Party services

GET Party

HTTP Request

Response examples

PUT party

Request Body examples

GET Party Answers

Response examples

Put Party Answers

Request body examples

Information Exchanges

Retrieving Information Exchange data from a dossier

Retrieve all Information Exchanges from a dossier

HTTP Request

Response examples

Retrieve a specific Information Exchange from a dossier

HTTP Request

Response examples

Retrieve questionnaire answers from a specific Information Exchange

HTTP Request

Response examples

Create a new Information Exchange

HTTP Request

Request body examples

Response examples

Initiate a new Information Exchange

HTTP Request

Request body examples

Response examples

Cancel an open Information Exchange

HTTP Request

Create an external Information Exchange completion

HTTP Request

Request body examples