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.

{
    // general structure of client data
    "client": {
        "id": "<UUID>", // read-only: id of the client
        "clientNumber": "<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
        "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.
        }
    }
}
"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
    }]
}
"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
    }]
}
"profile": {
  "identityType": "corporate",
  "registrationAddress": {
    "country": "GB",
    "region": "England",
    "city": "London",
    "street": "Baker Street",
    "houseNumber": "221B",
    "postalCode": "XYZ ABC",
    "refinement": ""
  },
  "phone": "+441234567890",
  "email": "[email protected]"
}
"profile": {
  "identityType": "individual",
  "residentialAddress": {
    "country": "GB",
    "region": "England",
    "city": "London",
    "street": "Baker Street",
    "houseNumber": "221B",
    "postalCode": "XYZ ABC",
    "refinement": ""
  },
  "phone": "+441234567890",
  "email": "[email protected]"
}
"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": "[email protected]"
  }
}]

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 you will be asked to supply a client id in order to ensure the Client is the owner of the account.

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.
    • 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 https://resources.companieshouse.gov.uk/sic/. 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.

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.

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"
          }
        ]
      },
      "profile": {
        "identityType": "individual",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        },
        "phone": "+441234567890",
        "email": "[email protected]"
      }
    }
  },
  "connect": {},
  "metadata": {}
}
POST /clients
{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "client": {
      "identity": {
        "type": "corporate",
        "legalName": "I.F Technology Ltd",
        "incorporationDate": "1987-01-01",
        "country": "GB"
      },
      "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": "[email protected]"
          }
        }
      ]
    }
  },
  "connect": {},
  "metadata": {}
}
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"
                    }
                ]
            },
            "profile": {
                "identityType": "individual",
                "residentialAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "EC1Y 1AA",
                    "refinement": ""
                },
                "phone": "1012555123",
                "email": "[email protected]"
            },
            "attributes": {
                "accountUsage": "sendAndReceiveMoneyTransfers",
                "riskScore": "low",
                "isPep": "false",
                "expectedVolumeRange": "5001-10000",
                "expectedVolumeType": "monthly",
                "expectedVolumeCurrency": "GBP"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
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"
            },
            "profile": {
                "registrationAddress": {
                    "country": "GB",
                    "region": "Dewsbury Moor",
                    "city": "Dewsbury",
                    "street": "98 Low Rd",
                    "houseNumber": "15",
                    "postalCode": "WF13 3PS",
                    "refinement": ""
                },
                "identityType": "corporate",
                "phone": "1012555123",
                "email": "[email protected]"
            },
            "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.

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"
          }
        ]
      },
      "profile": {
        "identityType": "individual",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        },
        "phone": "+441234567890",
        "email": "[email protected]"
      }
    }
  },
  "connect": {},
  "metadata": {}
}
{
  "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"
          }
        ]
      },
      "profile": {
        "identityType": "individual",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        },
        "phone": "+441234567890",
        "email": "[email protected]"
      },
      "fullName": "Canay Özel"
    },
    "user": {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "[email protected]",
      "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.

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

// the request below only updates the identity & profile of the individual client
PATCH /clients/<client-id>
{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "client": {
      "identity": {
        "type": "individual",
        "givenName": "Michael",
        "familyName": "Johnson",
        "birthDate": "1953-01-06",
        "country": "GB"
      },
      "profile": {
        "identityType": "individual",
        "phone": "+4412345678",
        "email": "[email protected]",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "EC1Y 1AA"
        }
      }
    }
  },
  "connect": {},
  "metadata": {}
}
// the request below only updates the identity & the profile of the corporate client
PATCH /clients/<client-id>
{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "client": {
      "identity": {
        "type": "corporate",
        "legalName": "I.F Technology Ltd",
        "incorporationDate": "1987-01-01",
        "country": "GB",
        "corporationType":"ltd"
      },
      "profile": {
        "identityType": "corporate",
        "phone": "+441234567890",
        "email": "[email protected]",
        "registrationAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "City Road",
          "houseNumber": "Epworth House 1",
          "postalCode": "EC1Y 1AB"
        }
      }
    }
  },
  "connect": {},
  "metadata": {}
}
// the request below only updates the identity & profile & attributes of the individual client
PATCH /clients/<client-id>
{
    "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"
                    }
                ]
            },
            "profile": {
                "identityType": "individual",
                "residentialAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "EC1Y 1AA",
                    "refinement": ""
                },
                "phone": "1012555128",
                "email": "[email protected]"
            },
            "attributes": {
                "accountUsage": "sendAndReceiveMoneyTransfers",
                "riskScore": "low",
                "isPep": "false",
                "expectedVolumeRange": "5001-10000",
                "expectedVolumeType": "monthly",
                "expectedVolumeCurrency": "GBP"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
// the request below only updates the identity & the profile & attributes of the corporate client
PATCH /clients/<client-id>
{
    "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"
            },
            "profile": {
                "registrationAddress": {
                    "country": "GB",
                    "region": "Dewsbury Moor",
                    "city": "Dewsbury",
                    "street": "98 Low Rd",
                    "houseNumber": "17",
                    "postalCode": "WF13 3PS",
                    "refinement": ""
                },
                "identityType": "corporate",
                "phone": "1012555129",
                "email": "[email protected]"
            },
            "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.

{
    "workflow": {},
    "data": {
        "client": {
            "identity": {
                "type": "corporate",
                "legalName": "I.F Technology Ltd",
                "incorporationDate": "1987-01-01",
                "country": "GB"
            },
            "profile": {
                "identityType": "corporate",
                "registrationAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "XYZ ABC",
                    "refinement": ""
                },
                "phone": "+441234567890",
                "email": "[email protected]"
            }
        }
    },
    "connect": {},
    "metadata": {
        "includeProfile": true,
        "includePrimaryAddress": true
    }
}

You can find a list of valid included parameters below

KeyDescription
data.client.profile.primaryAddressIncludes residential address if client identity type is individual, registration address if client identity type is corporate.
data.client.profile.residentialAddressIncludes residential address if client identity type is individual.
data.client.profile.registrationAddressIncludes registration address if client identity type is corporate.
connect.connectionsIncludes information about existing connections of the client.

List Clients

GET /clients

The complete list of parameters can be found in the technical reference documentation.

{
  "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"
        },
        "profile": {
          "identityType": "corporate",
          "phone": "+441234567890",
          "email": "[email protected]"
        },
        "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": "[email protected]"
        },
        "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.
{
  "webhook": {
    "module": "clients",
    "type": "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"
      },
      "profile": {
        "identityType": "corporate",
        "phone": "+441234567890",
        "email": "[email protected]"
      },
      "fullName": "I.F Technology Ltd"
    }
  },
  "connect": {},
  "metadata": {}
}
{
  "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"
      },
      "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

{
  "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": "[email protected]"
      }
    }
  },
  "connect": {},
  "metadata": {}
}
{
  "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": "[email protected]"
      }
    }
  },
  "connect": {},
  "metadata": {}
}
{
  "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": "[email protected]"
        }
      }
    ]
  },
  "connect": {},
  "metadata": {}
}
{
  "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": "[email protected]"
        }
      }
    ]
  },
  "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.

{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "clientRelation": {
      "relation": "director-and-shareholder",
      "profile": {
        "identityType": "individual",
        "phone": "+441234567890",
        "email": "[email protected]"
      }
    }
  },
  "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}

{
  "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": "[email protected]"
      },
      "fullName": "John Doe"
    }
  },
  "connect": {},
  "metadata": {}
}

List Client Relations

All relations of a client can be listed using this endpoint.

GET /clients/{clientId}/relations

{
  "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": "[email protected]"
        },
        "fullName": "John Doe"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 20,
      "number": 0,
      "totalElements": 1,
      "totalPages": 1
    }
  }
}