Skip to main content

Onboard your customers

info

This guide is about using our API to onboard your customers. Getting your own company onboarded with Griffin is a separate process. For more information, contact us.

This guide will take you through how to integrate your applications with Verify, our automated onboarding product for running KYC/KYB checks on your customers. If you’re a customer of our (future) banking products, you will also need to use this process to verify your customers.

This guide assumes you know your $GRIFFIN_API_KEY and $ORGANIZATION_ID already. If you don't, your first step should be to get started with the API.

For now, we only support onboarding for customers who are companies. Support for onboarding individual human customers is coming soon!

Overview

There are four steps to onboarding a customer.

  1. Look up Companies House record (optional)
  2. Capture company directors and ultimate beneficial owners
  3. Supply company information
  4. Verification

There is no time limit for gathering the information for each step.

1. Lookup Companies House record

The first thing you need is the company information for the customer you wish to onboard. You can get this by querying Companies House with their company number, as shown below. If you already have this information, you can skip to step 2.

curl 'https://api.griffin.sh/v0/companies-house/companies/99999999' \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json'

On success, you will see the following company information. You will use this in the next steps to create entities representing the company, its directors, and ultimate beneficial owners.

{
"entity-registration-number": "99999999",
"entity-name": "MONEY TECHNOLOGY LTD.",
"corporation-type": "private-limited-company",
"date-of-incorporation": "2017-06-29",
"company-status": "active",
"confirmation-statement-overdue": false,
"date-of-latest-confirmation-statement": "2020-01-01",
"accounts-overdue": false,
"date-of-latest-accounts": "2020-01-01",
"company-address": {
"street-name": "Argyle Street",
"city": "London",
"postal-code": "EC2V 9AN",
"country-code": "GB"
},
"directors": [
{
"display-name": "SMITH, John",
"director-occupation": "Chief Executive Officer",
"director-appointed-on": "2020-01-01",
"month-of-birth": 1,
"year-of-birth": 1970,
"companies-house-url": "https://api.company-information.service.gov.uk/company/99999999/appointments/abc123"
}
],
"persons-with-significant-control": [
{
"display-name": "Bloggs, Joe",
"given-name": "Joe",
"surname": "Bloggs",
"month-of-birth": 1,
"year-of-birth": 1970,
"natures-of-control": [
"ownership-of-shares-25-to-50-percent"
],
"companies-house-url": "https://api.company-information.service.gov.uk/company/99999999/persons-with-significant-control/individual/def456"
}
]
}

2. Capture company directors and ultimate beneficial owners

The company, its directors and ultimate beneficial owners are all represented as legal persons. The company is categorised as a corporation legal person. Directors and ultimate beneficial owners are individual legal persons, and their connection to the corporation is represented by the director and ultimate-beneficial-owner claims.

For each individual you want to run checks on, you need to create a legal person and then add claims about them. You will need their name, date of birth, residential address, and email address; each of these represents one claim. You can create the legal person and add their claims all in one go, as shown below.

curl "https://api.griffin.sh/v0/organizations/${ORGANIZATION_ID}/legal-persons" \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
-d \
'{
"display-name": "John Smith",
"legal-person-type": "individual",
"claims": [
{
"claim-type": "individual-identity",
"claim-data": {
"date-of-birth": "1960-01-01",
"given-name": "John",
"surname": "Smith"
}
},
{
"claim-type": "individual-residence",
"claim-data": {
"building-number": "123",
"street-name": "test street",
"city": "test city",
"postal-code": "TE1 2ST",
"country-code": "GB"
}
},
{
"claim-type": "contact-details",
"claim-data": {
"email-address": "someone@example.com"
}
}
]
}'

A successful response will have a 201 status code. The URL addressing the newly created legal person (e.g. /v0/legal-persons/lp.njk7tIWvQJGPEFIdDmS9yQ) will be present at both the response's Location header and the legal-person-url in the response body. Save this URL so you can associate it with the company in the next step.

info

In this example, you create the legal person and their claims in one go, but you can also create claims independently. See the API reference for more information about the different claims and their requirements.

3. Supply company information

Once you've created a legal person for each individual you need to run checks on, you need to create a corporation legal person representing the company. This involves creating a company claim using the information collected in step 1 and a claim linking each director and ultimate beneficial owner to the company.

curl "https://api.griffin.sh/v0/organizations/${ORGANIZATION_ID}/legal-persons" \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
-d \
'{
"display-name": "Acme Corp",
"legal-person-type": "corporation",
"claims": [
{
"claim-type": "uk-company-register",
"claim-data": {
"entity-name": "Acme Corp",
"corporation-type": "private-limited-company",
"entity-registration-number": "00000001",
"date-of-incorporation": "2000-01-01",
"building-number": "123",
"city": "Test City",
"street-name": "Test Street",
"postal-code": "TE1 2ST",
"country-code": "GB"
}
},
{
"claim-type": "director",
"claim-data": {
"legal-person-url": "/v0/legal-persons/lp.njk7tIWvQJGPEFIdDmS9yQ"
}
},
{
"claim-type": "ultimate-beneficial-owner",
"claim-data": {
"legal-person-url": "/v0/legal-persons/lp.njk7tIWvQJGPEFIdDmS9yQ",
"ownership-percent": "10"
}
}
]
}'
info

An individual legal person can be both a director and an ultimate beneficial owner for the same company. An individual legal person can also be a director and ultimate beneficial owner for multiple companies.

4. Choose your workflow

To create a verification, you need to supply the workflow you want to run. You can see the available workflows for your organization by querying organization-workflows-url, as shown below. If you already have this information, you can skip to the next step.

curl "https://api.griffin.sh/v0/organizations/${ORGANIZATION_ID}/workflows" \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \

The response will look like this.

{
"workflows": [
{
"workflow-url": "/v0/workflows/wf.s4YCYXWDVnq4N7vrJKp_pw",
"display-name": "Sample workflow",
"legal-person-type": "corporation"
}
]
}

5. Verification

Once all directors and ultimate beneficial owners have been added with the correct information, you can submit for verification. Verification is a series of checks you run on a legal person to a) make sure they are who they say they are and b) figure out what level of financial crime risk they pose.

The verification process is asynchronous and runs as follows.

  • The verification starts in a pending state and a response is served immediately, including the verification-url.
  • Outside of the request/response cycle, the verification may transition to in-progress and then to the final state of checks-complete.
  • Once the verification reaches checks-complete, a decision can be created.
  • The verification may also transition to failed from either the pending or in-progress states if there is an error when communicating with our verification providers.
info

The verification is created against the corporation legal person. This means checks will be performed on that legal person, as well as any individual legal persons connected to it via the director or ultimate beneficial owner claims.

curl 'https://api.griffin.sh/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45/verifications' \
-X 'POST'
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"workflow-url": "/v0/workflows/wf.s4YCYXWDVnq4N7vrJKp_pw"}'

The response will look like this. You'll need the verification-url for monitoring.

{
"created-at": "2022-08-15T10:47:51.959Z",
"display-name": "MONEY TECHNOLOGY LTD.",
"legal-person-type": "corporation",
"legal-person-url": "/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
"updated-at": "2022-08-15T10:47:51.959Z",
"verification-status": "pending",
"verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA",
"workflow-url": "/v0/workflows/wf.s4YCYXWDVnq4N7vrJKp_pw"
}

Monitoring the verification

You can poll the verification-url to monitor the verification.

curl 'https://api.griffin.sh/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA' -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

The processing is finished when the verification-status reaches checks-complete. Here is an example of the response you might see:

{
"created-at": "2022-08-15T10:47:51.959Z",
"display-name": "MONEY TECHNOLOGY LTD.",
"legal-person-type": "corporation",
"legal-person-url": "/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
"risk-rating": "low-risk",
"updated-at": "2022-08-15T10:48:03.215Z",
"verification-status": "checks-complete",
"verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA",
"workflow-url": "/v0/workflows/wf.s4YCYXWDVnq4N7vrJKp_pw"
}

Monitoring the application status

You can poll the legal-person-url to monitor the application-status for the company.

curl 'https://api.griffin.sh/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45' -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

Once the verification reaches checks-complete, the application-status will change to accepted or declined, or referred (if no decision was made).

The response will include application-status and also the latest-decision when one exists, as shown below:

{
"latest-decision":
{
"verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA",
"decision-outcome": "accepted",
"decision-maker": "user",
"decision-notes": "Looks good to me!",
"decision-user-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
"created-at": "2022-08-15T10:47:51.959Z"
},
"display-name": "Company name",
"application-status": "accepted",
"status-changed-at": "2019-08-24T14:15:22Z",
"created-at": "2019-08-24T14:15:22Z",
...
}

Customer decision

Once you have your verification results, you can make a decision to either accept or decline the customer.

curl 'https://api.griffin.sh/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45/decisions' \
-H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
-H 'Content-Type: application/json' \
-d \
'{
"decision-notes": "The results indicate this customer is within our risk threshold.",
"decision-outcome": "accepted",
"verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA"
}'