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.
{
// 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.
}]
}
}
"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.
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": {}
}
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.
// 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": {}
}
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
| 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
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
}
}
}
Updated 3 months ago