--- updatedAt: 2025-10-30T11:40:34.000Z agentTools: projectIndex: https://developer.integrated.finance/llms.txt --- # Clients A client is a legal entity that uses your solution. There can be two types of client. **Individual:** This type of client corresponds to a natural person.\ **Corporate:** This type of clients correspond to a corporate entity such as companies, charities etc. The example below explains the data structure for clients. ```json Client Data Structure { // general structure of client data "client": { "id": "", // read-only: id of the client "clientNumber": "", // read-only: user firendly client identifier "fullName": "Given+Family Name or Legal Name", // read-only: client's full name in a single field "status": "active", // read-only: client's status "risk": "medium", // optional risk of the client "identity": {}, // changes depending of the type of the client "profile": { ... // subresources to send when saving client }, "relations": [{ ... // optional related legal entities like directors, shareholders etc. "attributes": { ... // optional service provider entities like riskScore, accountUsage etc. } } } ``` ```json Corporate Identity "identity": { "type": "corporate", // required "legalName": "ACME INC.", // required "incorporationDate": "2000-01-01", "corporationType": "ltd", "country": "GB", // registered country "identificationNumbers": { // optional - deprecated "registration-number": "123456789" }, "identifications": [{ // optional "type": "registration-number", // required "identificationNumber": "12345678", // required "issuingCountry": "GB", // optional "issueDate": "2022-01-01", // optional "expirationDate": "2023-01-01" // optional }] } ``` ```json Individual Identity "identity": { "type": "individual", // required "givenName": "John", // required "familyName": "Doe", // required "birthDate": "2000-01-01", "country": "GB", // nationality "identificationNumbers": { // optional - deprecated "passport": "123456789" }, "identifications": [{ // optional "type": "passport", // required "identificationNumber": "12345678", // required "issuingCountry": "GB", // optional "issueDate": "2022-01-01", // optional "expirationDate": "2023-01-01" // optional }] } ``` ```json Corporate Profile "profile": { "identityType": "corporate", "registrationAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } ``` ```json Individual Profile "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } ``` ```json Individual Relation of Corporates "relations": [{ "relation": "director", // one of: director, shareholder, director-and-shareholder, authorized-person "identity": { "type": "individual", // required "givenName": "John", // required "familyName": "Doe", // required "birthDate": "2000-01-01", "country": "GB" // nationality }, "profile": { "identityType": "individual", "residentialAddress": { "city": "London", "state": null, "country": "GB", "firstLine": "Line1", "postalCode": "100001", "secondLine": "Line2" }, "phone": "+441234567890", "email": "abc@integrated.finance" } }] ``` If *country* of an address is US, CA or MX, *region* must be sent as alpha-2 (ISO 3166-2) code of the state. For other countries, *region* is a free text field. Certain modules in the IF Platform depend on Clients. For instance, to create an account via the [Accounts module](/docs/accounts) you will be asked to supply a client id in order to ensure the Client is the owner of the account. *risk*: It is an optional field that can be one of the following values: low, medium, high, or severe. It indicates the client's risk level. *attributes*: A key-value map that can store any additional metadata you'd like to link to the client. There are some reserved keys for each service provider. * *railsbank*'s reserved attributes: * *accountUsage*: Details about how the account will be used. Required for Railsbank individual and corporate clients. Allowed values for individual clients are *digitalAssets*, *gamingOrBetting*, *socialWelfarePayments*, *savings*, *salary*, *sendAndReceiveMoneyTransfers*, *inheritance*, *investments*, *incomeFromBusinessActivity*, *personalExpenses*, *other*. Allowed values for corporate clients are *companyExpenses*, *settlements*, *other*, *serviceProviderPayments*, *receiveClientFunds*, *intragroupTransactions*. * *otherNotes*: When “other” type is used for *accountUsage* then this field becomes mandatory to explain account usage in free text up to 30 characters. * *riskScore*: Assessed risk level of the client. Required for Railsbank individual and corporate clients. Allowed values are *low*, *high*, *lowMedium*, *mediumHigh*, *medium* etc. * *expectedVolumeRange*: Range of the expected transaction volumes. Required for Railsbank individual and corporate clients. Allowed values for individual clients are *0-5000*, *5001-10000*, *10000+*. Allowed values for corporate clients are *250000-1000000*, *50000-250000*, *1000000+*, *0-25000*, *25000-50000*. * *expectedVolumeType*: Define frequency for the expected volume range. Required for Railsbank individual and corporate clients. Allowed value is *monthly*. * *expectedVolumeCurrency*: Currency of expected transaction volumes. Required for Railsbank individual and corporate clients. Provided as an ISO 4217 currency code. Allowed values are *EUR*, *GBP*. * *isPep*: Indicates if the person is a Politically Exposed Person. Required for Railsbank individual clients. Must be either *true* or *false*. * *companyType*: Type of company and required for Railsbank corporate clients. Allowed values are *soleTrader*, *partnership*, *private*, *nonProfit*, *communityInterest*, *public*, *internationalNGO*. * *businessNatures*: List of Standard Industrial Classification (SIC) codes representing the company's business activities. Codes can be found at . Required for corporate client of company types: *private*, *public*, *soleTrader*, *partnership*. Allowed values are. *45320*, *20200*, *24450*, *01250*, *29201*, *82200* etc. * *nonBusinessNature*: Description of activities not covered by SIC codes. Required for corporate client of company types: *nonProfit*, *communityInterest*, *internationalNGO*. Free text field up to 1000 characters. * *charitableBeneficiaries*: Description of beneficiary groups that benefit from this entity. Required for corporate client of company type: *nonProfit*. Free text field up to 1000 characters. * *legalStatusOfEntity*: Details the legal status of the enduser entity in cases where this data cannot be collected from a publicly accessible registry. Required for corporate client of company types: *nonProfit*, *communityInterest*, *internationalNGO*. Free text field up to 1000 characters. * *website*: Company's official website URL. Must be a valid URL. Required for company types: *public*, *internationalNGO*. * *legalFormOfPartnership*: Details legal form of the partnership. This will effect the type of associated persons which are expected to be seen for partnership. Required for corporate client of company type: *partnership*. ## **Creating a Client** Currently there are 2 workflows to create clients. If you are utilising a third party onboarding tool integrated into your environment (such as SumSub), the clients will be created once they have been verified, without needing a API request, with all the client details collected from the third party tool. You would then receive a client-created webhook when this occurs with all those details. ### **1. Direct Workflow: Directly Supplying Client Information** This workflow is useful when the system you are integrating to the IF Platform is the controller of client data. The code for this workflow is "direct". Using this workflow, at a minimum, the client identity and address must be provided. To provide address information, for individual clients, the **residential address** field must be used.\ For corporate clients, the **registration address** field must be used. A list of related individuals (relations) can be added on client creation for corporate clients only. A maximum of 10 relations can be added at the time of client creation, however more can be added using the dedicated API for adding relations. ```json Clients Create Direct - Individual POST /clients { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "individual", "givenName": "Canay", "familyName": "Özel", "birthDate": "1987-01-01", "country": "TR", "identifications": [ { "type": "identity-card", "identificationNumber": "12345678", "issuingCountry": "TR", "issueDate": "2022-01-01", "expirationDate": "2023-01-01" } ] }, "risk": "low", "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } }, "connect": {}, "metadata": {} } ``` ```json Clients Create Direct - Corporate POST /clients { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "corporate", "legalName": "I.F Technology Ltd", "incorporationDate": "1987-01-01", "country": "GB" }, "risk": "low", "profile": { "identityType": "corporate", "registrationAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890" }, "relations": [ { "relation": "director", "identity": { "type": "individual", "givenName": "John", "familyName": "Doe", "birthDate": "2000-01-01", "country": "GB" }, "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } ] } }, "connect": {}, "metadata": {} } ``` ```json Clients Create Direct - Individual RLB POST /clients { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "individual", "givenName": "Railsr", "familyName": "Rlb", "birthDate": "1987-01-01", "country": "GB", "identifications": [ { "type": "identity-card", "identificationNumber": "12345677", "issuingCountry": "GB", "issueDate": "2022-01-01", "expirationDate": "2032-01-01" } ] }, "risk": "medium", "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "EC1Y 1AA", "refinement": "" }, "phone": "1012555123", "email": "abc@integrated.finance" }, "attributes": { "accountUsage": "other", "otherNotes": "free text field", "riskScore": "low", "isPep": "false", "expectedVolumeRange": "5001-10000", "expectedVolumeType": "monthly", "expectedVolumeCurrency": "GBP" } } }, "connect": {}, "metadata": {} } ``` ```json Clients Create Direct - Corporate RLB POST /clients { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "corporate", "legalName": "Foo Bar Inc.", "tradingName": "", "country": "GB", "identifications": [ { "type": "registration-number", "identificationNumber": "12345678" } ], "incorporationDate": "2019-09-09", "corporationType": "ltd" }, "risk": "medium", "profile": { "registrationAddress": { "country": "GB", "region": "Dewsbury Moor", "city": "Dewsbury", "street": "98 Low Rd", "houseNumber": "15", "postalCode": "WF13 3PS", "refinement": "" }, "identityType": "corporate", "phone": "1012555123", "email": "abc@integrated.finance" }, "addresses": { "tradingAddress": { "country": "GB", "region": "Dewsbury Moor", "city": "Dewsbury", "street": "92 Low Rd", "houseNumber": "21", "postalCode": "WF13 3PS", "refinement": "" } }, "attributes": { "accountUsage": "receiveClientFunds", "riskScore": "low", "expectedVolumeRange": "0-25000", "expectedVolumeType": "monthly", "expectedVolumeCurrency": "GBP", "businessNatures": "20200", "companyType": "private", "website": "https//www.abc.com" }, "relatedLegalEntities": [ { "relation": "director", "identity": { "type": "individual", "givenName": "foo", "familyName": "bar", "birthDate": "1987-01-01", "country": "GB" }, "profile": { "phone": "", "addresses": { "residential": { "country": "GB", "postalCode": "12345", "city": "London", "street": "122B Baker street" } } } }, { "relation": "shareholder", "identity": { "type": "corporate", "country": "GB", "identificationNumbers": null, "legalName": "Sub foo bar", "incorporationDate": "2019-09-09", "corporationType": null }, "profile": { "phone": "", "addresses": { "registration": { "country": "GB", "postalCode": "12345", "city": "London", "street": "122B Baker street" } } } }, { "relation": "director-and-shareholder", "identity": { "type": "individual", "givenName": "sub 2 foo", "familyName": "bar", "birthDate": "1987-01-01", "country": "GB" }, "profile": { "phone": "", "addresses": { "residential": { "country": "GB", "postalCode": "12345", "city": "London", "street": "122B Baker street" } } } } ] } }, "connect": {}, "metadata": {} } ``` #### **Automatic User Creation Workflow for Individual Clients** *createUser* workflow attribute can be used to trigger a user creation using the information provided for an individual client. Email of client must be provided to enable this workflow. Response object contains both client and user data. ```json Clients Create Direct - Automatic User Creation - Request POST /clients { "workflow": { "code": "direct", "createUser": true }, "data": { "client": { "identity": { "type": "individual", "givenName": "Canay", "familyName": "Özel", "birthDate": "1987-01-01", "country": "TR", "identifications": [ { "type": "identity-card", "identificationNumber": "12345678", "issuingCountry": "TR", "issueDate": "2022-01-01", "expirationDate": "2023-01-01" } ] }, "risk": "medium", "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } }, "connect": {}, "metadata": {} } ``` ```json Clients Create Direct - Automatic User Creation - Response { "workflow": { "code": "direct", "createUser": true }, "data": { "client": { "id": "00000000-0000-0000-0000-000000000000", "clientNumber": "20663251", "status": "active", "identity": { "type": "individual", "givenName": "Canay", "familyName": "Özel", "birthDate": "1987-01-01", "country": "TR", "identifications": [ { "type": "identity-card", "identificationNumber": "12345678", "issuingCountry": "TR", "issueDate": "2022-01-01", "expirationDate": "2023-01-01" } ] }, "risk": "medium", "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "canay.ozel@integrated.finance" }, "fullName": "Canay Özel" }, "user": { "id": "00000000-0000-0000-0000-000000000000", "email": "canay.ozel@integrated.finance", "identity": { "type": "individual", "givenName": "Canay", "familyName": "Özel", "birthDate": "1987-01-01", "country": "TR", "identifications": [ { "type": "identity-card", "identificationNumber": "12345678", "issuingCountry": "TR", "issueDate": "2022-01-01", "expirationDate": "2023-01-01" } ] }, "category": "external", "type": "human" }, "userClientRelation": { "id": "00000000-0000-0000-0000-000000000000", "userId": "00000000-0000-0000-0000-000000000000", "clientId": "00000000-0000-0000-0000-000000000000", "status": "allowed" } }, "connect": {}, "metadata": {} } ``` ### **2. Create Client with Data from an External System** This workflow is useful when you want to create a client with the data from an external system, such as your CRM or Financial Provider. If the IF Platform is integrated with your CRM only the identifier of the client on your CRM is required. ```json Migrate Client from Service Provider POST /clients { "workflow": { "code": "migration" }, "data": { "sourceId": "00000000-0000-0000-0000-000000000000" }, "connect": { "type": "explicit", "serviceProvider": "railsbank" }, "metadata": {} } ``` ## **Updating a Client** Currently there are 2 workflows to update clients. ### **1. Direct Workflow: Directly Supplying Client Information** It is not necessary to provide a full object since the IF Platform uses patch style updates on entities.\ Please ensure that when update the client profile object, the entire profile object is included in the request, not just the fields being changed. This includes all relevant details, such as the identityType and any other associated data, to ensure the profile is fully updated ```json Clients Update Direct - Individual // the request below only updates the identity & profile of the individual client PATCH /clients/ { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "individual", "givenName": "Michael", "familyName": "Johnson", "birthDate": "1953-01-06", "country": "GB", }, "risk": "severe", "profile": { "identityType": "individual", "phone": "+4412345678", "email": "a@b.com", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "EC1Y 1AA" } } } }, "connect": {}, "metadata": {} } ``` ```json Clients Update Direct - Corporate // the request below only updates the identity & the profile of the corporate client PATCH /clients/ { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "corporate", "legalName": "I.F Technology Ltd", "incorporationDate": "1987-01-01", "country": "GB", "corporationType":"ltd" }, "risk": "low", "profile": { "identityType": "corporate", "phone": "+441234567890", "email": "a@b.com", "registrationAddress": { "country": "GB", "region": "England", "city": "London", "street": "City Road", "houseNumber": "Epworth House 1", "postalCode": "EC1Y 1AB" } } } }, "connect": {}, "metadata": {} } ``` ```json Clients Update - Individual RLB // the request below only updates the identity & profile & attributes of the individual client PATCH /clients/ { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "individual", "givenName": "Connect Individual", "familyName": "Railsbank", "birthDate": "1996-01-01", "country": "GB", "identifications": [ { "type": "identity-card", "identificationNumber": "12345677", "issuingCountry": "GB", "issueDate": "2022-01-01", "expirationDate": "2032-01-01" } ] }, "risk": "severe", "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "EC1Y 1AA", "refinement": "" }, "phone": "1012555128", "email": "abc@integrated.finance" }, "attributes": { "accountUsage": "sendAndReceiveMoneyTransfers", "riskScore": "low", "isPep": "false", "expectedVolumeRange": "5001-10000", "expectedVolumeType": "monthly", "expectedVolumeCurrency": "GBP" } } }, "connect": {}, "metadata": {} } ``` ```json Clients Update - Corporate RLB // the request below only updates the identity & the profile & attributes of the corporate client PATCH /clients/ { "workflow": { "code": "direct" }, "data": { "client": { "identity": { "type": "corporate", "legalName": "Foo Bar Inc.", "tradingName": "", "country": "GB", "risk": "low", "identifications": [ { "type": "registration-number", "identificationNumber": "12345678" } ], "incorporationDate": "2019-09-09", "corporationType": "ltd" }, "risk": "severe", "profile": { "registrationAddress": { "country": "GB", "region": "Dewsbury Moor", "city": "Dewsbury", "street": "98 Low Rd", "houseNumber": "17", "postalCode": "WF13 3PS", "refinement": "" }, "identityType": "corporate", "phone": "1012555129", "email": "abc@mail.com" }, "addresses": { "trading": { "country": "GB", "region": "Dewsbury Moor", "city": "Dewsbury", "street": "92 Low Rd", "houseNumber": "21", "postalCode": "WF13 3PS", "refinement": "" } }, "attributes": { "accountUsage": "receiveClientFunds", "riskScore": "low", "expectedVolumeRange": "0-25000", "expectedVolumeType": "monthly", "expectedVolumeCurrency": "GBP", "businessNatures": "20200", "companyType": "private", "website": "https//www.abc.com" } } }, "connect": {}, "metadata": {} } ``` ## **Accessing Client Data** ### **Get a Client** Endpoints with the GET method does not include workflows; however you can use metadata parameters to shape the response. ***GET /clients/\{clientId}?metadata.includeProfile=true\&metadata.include=data.client.profile.primaryAddress*** The complete list of parameters can be found in the technical reference documentation. ```json response { "workflow": {}, "data": { "client": { "identity": { "type": "corporate", "legalName": "I.F Technology Ltd", "incorporationDate": "1987-01-01", "country": "GB" }, "risk": "low", "profile": { "identityType": "corporate", "registrationAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } }, "connect": {}, "metadata": { "includeProfile": true, "includePrimaryAddress": true } } ``` You can find a list of valid included parameters below | Key | Description | | :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | data.client.profile.primaryAddress | Includes residential address if client identity type is individual, registration address if client identity type is corporate. | | data.client.profile.residentialAddress | Includes residential address if client identity type is individual. | | data.client.profile.registrationAddress | Includes registration address if client identity type is corporate. | | connect.connections | Includes information about existing connections of the client. | ### **List Clients** ***GET /clients*** **Supported query parameters:** | parameter | description | | :------------------------ | :--------------------------------------------------- | | metadata.page.number | 0-indexed, default=0 | | metadata.page.size | default=20, max=100 | | data.client.identity.type | individual or corporate | | data.client.status | active or inactive | | data.client.fullName | Free text full client name | | data.client.clientNumber | Client number | | data.client.risk | Client risk. It can be low, medium, high, or severe. | ```json response { "workflow": {}, "data": { "clients": [ { "id": "00000000-0000-0000-0000-000000000000", "clientNumber": "20663251", "status": "active", "identity": { "type": "corporate", "legalName": "I.F Technology Ltd", "incorporationDate": "2020-01-01", "country": "GB" }, "risk": "severe", "profile": { "identityType": "corporate", "phone": "+441234567890", "email": "abc@integrated.finance" }, "fullName": "I.F Technology Ltd" }, { "id": "00000000-0000-0000-0000-000000000001", "clientNumber": "20663241", "status": "active", "identity": { "type": "individual", "givenName": "Canay", "familyName": "Özel", "birthDate": "1987-01-01", "country": "TR" }, "profile": { "identityType": "individual", "phone": "+441234567890", "email": "abc@integrated.finance" }, "fullName": "Canay Özel" } ] }, "connect": {}, "metadata": { "page": { "size": 20, "totalElements": 2, "totalPages": 1, "number": 0 } } } ``` ## **Webhooks** Client webhooks have "clients" as the module in the webhook container object. There are 2 types of webhooks sent for clients: * created * connection-created\ Type is exposed in *webhook.type* field. ```json Created Example { "webhook": { "module": "clients", "type": "created" }, "data": { "client": { "id": "00000000-0000-0000-0000-000000000000", "clientNumber": "20663251", "status": "active", "risk": "medium", "identity": { "type": "corporate", "legalName": "I.F Technology Ltd", "incorporationDate": "2020-01-01", "country": "GB" }, "risk": "medium", "profile": { "identityType": "corporate", "phone": "+441234567890", "email": "abc@integrated.finance" }, "fullName": "I.F Technology Ltd" } }, "connect": {}, "metadata": {} } ``` ```json Connection Created Example { "webhook": { "module": "clients", "type": "connection-created" }, "data": { "client": { "id": "00000000-0000-0000-0000-000000000000", "clientNumber": "20663251", "status": "active", "identity": { "type": "corporate", "legalName": "I.F Technology Ltd", "incorporationDate": "2020-01-01", "country": "GB" }, "risk": "low", "profile": { "identityType": "corporate", "phone": "+441234567890" }, "fullName": "I.F Technology Ltd" } }, "connect": { "connection": { "id": "5ffc8b9c-3073-4625-a55b-4ae69d657cc3", "serviceProvider": "railsbank" } }, "metadata": {} } ``` ## **Operations on Client Relations** ### **Create a Client Relation** There is only a single workflow on creation of a new client relation. ### **1. Direct Workflow: Directly Supplying Legal Entity Information** Currently, only corporate clients are allowed to have relations and those related legal entities can only be individuals. You can add a single relation by adding *clientRelation* in the payload, or multiple of them by adding *clientRelations* as an array to the payload. If both are supplied, the request will be rejected. A maximum of 10 relations can be added in a single API call. ***POST /clients/\{clientId}/relations*** ```json Corporate Client Relation Create - Direct - Individual - Request { "workflow": { "code": "direct" }, "data": { "clientRelation": { "relation": "director", "identity": { "type": "individual", "givenName": "John", "familyName": "Doe", "birthDate": "2000-01-01", "country": "GB" }, "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } }, "connect": {}, "metadata": {} } ``` ```json Corporate Client Relation Create - Direct - Individual - Response { "workflow": { "code": "direct" }, "data": { "clientRelation": { "id": "00000000-0000-0000-0000-000000000000", "clientId": "00000000-0000-0000-0000-000000000000", "relation": "director", "identity": { "type": "individual", "givenName": "John", "familyName": "Doe", "birthDate": "2000-01-01", "country": "GB" }, "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } }, "connect": {}, "metadata": {} } ``` ```json Corporate Client Relation Create - Direct - List of Individual - Request { "workflow": { "code": "direct" }, "data": { "clientRelations": [ { "relation": "director", "identity": { "type": "individual", "givenName": "John", "familyName": "Doe", "birthDate": "2000-01-01", "country": "GB" }, "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } ] }, "connect": {}, "metadata": {} } ``` ```json Corporate Client Relation Create - Direct - List of Individual - Response { "workflow": { "code": "direct" }, "data": { "clientRelations": [ { "id": "00000000-0000-0000-0000-000000000000", "clientId": "00000000-0000-0000-0000-000000000000", "relation": "director", "identity": { "type": "individual", "givenName": "John", "familyName": "Doe", "birthDate": "2000-01-01", "country": "GB" }, "profile": { "identityType": "individual", "residentialAddress": { "city": "London", "state": null, "country": "GB", "firstLine": "Line1", "postalCode": "100001", "secondLine": "Line2" }, "phone": "+441234567890", "email": "abc@integrated.finance" } } ] }, "connect": {}, "metadata": {} } ``` ### **Update a Client Relation** There is only a single workflow to create a new client relation. ### **1. Direct Workflow: Directly Supplying Legal Entity Information** It is not necessary to provide the full object since the IF Platform uses patch style updates on entities. ***PATCH /clients/\{clientId}/relations/\{clientRelationId}*** The below example shows the request to update the *relation* and *phone* fields. ```json Corporate Client Relation Update - Direct - Individual { "workflow": { "code": "direct" }, "data": { "clientRelation": { "relation": "director-and-shareholder", "profile": { "identityType": "individual", "phone": "+441234567890", "email": "abc@integrated.finance" } } }, "connect": {}, "metadata": {} } ``` ### **Delete a Client Relation** There is no workflow on deleting operations. ***DELETE /clients/\{clientId}/relations/\{clientRelationId}*** ### **Get a Client Relation** Endpoints with GET do not include workflows. ***GET /clients/\{clientId}/relations/\{clientRelationId}*** ```json Corporate Client Relation Get - Individual { "workflow": {}, "data": { "clientRelation": { "id": "5a05cc06-0273-40aa-84dc-1846ad3c0942", "clientId": "ffa345d1-1cb6-44e4-bb1f-f4fb253f7a0e", "relation": "director-and-shareholder", "identity": { "type": "individual", "identificationNumbers": null, "givenName": "John", "familyName": "Doe", "birthDate": "2000-01-01", "country": "GB" }, "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" }, "fullName": "John Doe" } }, "connect": {}, "metadata": {} } ``` ### **List Client Relations** All relations of a client can be listed using this endpoint. ***GET /clients/\{clientId}/relations*** **Supported query parameters:** | parameter | description | | :-------------------------------- | :------------------------------------------------------------------------ | | metadata.page.number | 0-indexed, default=0 | | metadata.page.size | default=20, max=100 | | data.clientRelation.identity.type | individual or corporate | | data.clientRelation.relation | one of director, shareholder, director-and-shareholder, authorized-person | ```json Corporate Client Relation List { "workflow": {}, "data": { "clientRelations": [ { "id": "5a05cc06-0273-40aa-84dc-1846ad3c0942", "clientId": "ffa345d1-1cb6-44e4-bb1f-f4fb253f7a0e", "relation": "director-and-shareholder", "identity": { "type": "individual", "identificationNumbers": null, "givenName": "John", "familyName": "Doe", "birthDate": "2000-01-01", "country": "GB" }, "profile": { "identityType": "individual", "residentialAddress": { "country": "GB", "region": "England", "city": "London", "street": "Baker Street", "houseNumber": "221B", "postalCode": "XYZ ABC", "refinement": "" }, "phone": "+441234567890", "email": "abc@integrated.finance" }, "fullName": "John Doe" } ] }, "connect": {}, "metadata": { "page": { "size": 20, "number": 0, "totalElements": 1, "totalPages": 1 } } } ```