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
        "registration-number": "123456789"
    }
}
"identity": {
    "type": "individual", // required
    "givenName": "John", // required
    "familyName": "Doe", // required
    "birthDate": "2000-01-01",
    "country": "GB" // nationality
}
"profile": {
  "identityType": "corporate",
  "registrationAddress": {
    "country": "GB",
    "region": "England",
    "city": "London",
    "street": "Baker Street",
    "houseNumber": "221B",
    "postalCode": "XYZ ABC",
    "refinement": ""
  },
  "phone": "+441234567890"
}
"profile": {
  "identityType": "corporate",
  "residentialAddress": {
    "country": "GB",
    "region": "England",
    "city": "London",
    "street": "Baker Street",
    "houseNumber": "221B",
    "postalCode": "XYZ ABC",
    "refinement": ""
  },
  "phone": "+441234567890"
}
"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"
  }
}]

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.

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",
                "identificationNumbers": {
                    "identity-card": "5698421658"
                }
            },
            "profile": {
                "identityType": "individual",
                "residentialAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "XYZ ABC",
                    "refinement": ""
                },
                "phone": "+441234567890"
            }
        }
    },
    "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": {
              "city": "London",
              "state": null,
              "country": "GB",
              "firstLine": "Line1",
              "postalCode": "100001",
              "secondLine": "Line2"
            },
            "phone": "+441234567890"
          }
        }
      ]
    }
  },
  "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 birth date & address city
PATCH /clients/<client-id>
{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "client": {
            "identity": {
                "type": "individual",
                "birthDate": "1987-01-01",
            },
            "profile": {
                "identityType": "individual",
                "residentialAddress": {
                    "city": "London"
                },
                "phone": "+441234567890"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
// the request below only updates birth date & first line of the address
PATCH /clients/<client-id>
{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "client": {
            "identity": {
                "type": "corporate",
                "legalName": "I.F Technology Ltd",
            },
            "profile": {
                "identityType": "corporate",
                "registrationAddress": {
                    "firstLine": "Line1",
                },
                "phone": "+441234567890"
            }
        }
    },
    "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/?metadata.includeProfile=true&metadata.include=data.client.profile.primaryAddress

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

{
    "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"
            }
        }
    },
    "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?status=active

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"
                },
                "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"
                },
                "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 is 1 type of webhook sent for clients:

  • connection-created
    Type is exposed in webhook.type field.
{
    "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//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": {
          "city": "London",
          "state": null,
          "country": "GB",
          "firstLine": "Line1",
          "postalCode": "100001",
          "secondLine": "Line2"
        },
        "phone": "+441234567890"
      }
    }
  },
  "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": {
          "city": "London",
          "state": null,
          "country": "GB",
          "firstLine": "Line1",
          "postalCode": "100001",
          "secondLine": "Line2"
        },
        "phone": "+441234567890"
      }
    }
  },
  "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": {
          "city": "London",
          "state": null,
          "country": "GB",
          "firstLine": "Line1",
          "postalCode": "100001",
          "secondLine": "Line2"
        },
        "phone": "+441234567890"
      }
    }]
  },
  "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"
      }
    }]
  },
  "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//relations/

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"
      }
    }
  },
  "connect": {},
  "metadata": {}
}

Delete a Client Relation

There is no workflow on deleting operations.

DELETE /clients//relations/

Get a Client Relation

Endpoints with GET do not include workflows.

GET /clients//relations/

{
  "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": {
          "city": "London",
          "state": null,
          "country": "GB",
          "firstLine": "Line1",
          "postalCode": "100001",
          "secondLine": "Line2"
        },
        "phone": "+441234567890"
      },
      "fullName": "John Doe"
    }
  },
  "connect": {},
  "metadata": {}
}

List Client Relations

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

GET /clients//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": {
            "city": "London",
            "state": null,
            "country": "GB",
            "firstLine": "Line1",
            "postalCode": "100001",
            "secondLine": "Line2"
          },
          "phone": "+441234567890"
        },
        "fullName": "John Doe"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 20,
      "number": 0,
      "totalElements": 1,
      "totalPages": 1
    }
  }
}