Skip to main content

Onboard your customers

This guide will show you how to integrate your applications with Verify, our onboarding product for running automated KYC/KYB checks on your customers. This is also the first step for opening bank accounts for your customers with Griffin. Learn more about Verify.

This guide assumes you know your $GRIFFIN_API_KEY and $ORGANIZATION_ID already. If you don't, go get started with the API.

There are four steps to onboarding a customer.

  1. Capture customer information
  2. Choose your workflow
  3. Run the verification
  4. Make an onboarding decision

The first step will be different depending on what type of customer you want to onboard. Right now, we support onboarding for UK companies, individuals, and sole traders.

1. Capture customer information​

1.1 Lookup Companies House record​

Find the information for the UK company you wish to onboard by querying Companies House with their unique 8-digit company number. 

curl 'https://api.griffin.sh/v0/companies-house/companies/91824539' -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

A successful response will contain the following information about the company, its directors, and any other people with significant control (PSCs). PSCs are sometimes called beneficial owners. 

{
  "entity-registration-number": "91824539",
  "entity-name": "Money Technology Ltd.",
  "corporation-type": "private-limited-company",
  "date-of-incorporation": "2017-06-01",
  "company-status": "active",
  "confirmation-statement-overdue": false,
  "date-of-latest-confirmation-statement": "2022-01-01",
  "accounts-overdue": false,
  "date-of-latest-accounts": "2022-01-01",
  "company-address": {
    "street-name": "Argyle Street",
    "city": "London",
    "postal-code": "EC2V 9AN",
    "country-code": "GB"
  },
  "directors": [
    {
      "display-name": "JOHNSON, Talia",
      "director-occupation": "Chief Executive Officer",
      "director-appointed-on": "2018-03-05",
      "month-of-birth": 6,
      "year-of-birth": 1973,
      "companies-house-url": "https://api.company-information.service.gov.uk/company/91824539/appointments/abc123"
    }
  ],
  "persons-with-significant-control": [
    {
      "display-name": "CRANSTON, Robert",
      "given-name": "Robert",
      "surname": "Cranston",
      "month-of-birth": 1,
      "year-of-birth": 1969,
      "natures-of-control": [
        "ownership-of-shares-25-to-50-percent"
      ],
      "companies-house-url": "https://api.company-information.service.gov.uk/company/91824539/persons-with-significant-control/individual/def456"
    }
  ]
}

1.2 Capture company directors and PSCs​

The company, its directors, and its PSCs are all represented as legal persons in the API. The company is a corporation legal person. Directors and PSCs are individual legal persons.

To create an individual legal person to represent a director or PSC, you will need their:

  • full name and date of birth
  • residential address
  • email address

Each of these data points represent 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": "JOHNSON, Talia",
  "legal-person-type": "individual",
  "claims": [
    {
      "claim-type": "individual-identity",
      "date-of-birth": "1973-06-11",
      "given-name": "Talia",
      "surname": "Johnson"
    },
    {
      "claim-type": "individual-residence",
      "building-number": "12",
      "street-name": "Example Street",
      "city": "Test Town",
      "postal-code": "TE1 2ST",
      "country-code": "GB"
    },
    {
      "claim-type": "contact-details",
      "email-address": "talia@moneytechnology.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.

Create a corporation legal person representing the company, and use the information collected in step 1.1 to create a uk-company-register claim. Use director and person with significant control claims to associate the individual legal persons with 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": "Money Technology Ltd",
  "legal-person-type": "corporation",
  "claims": [
    {
      "claim-type": "uk-company-register",
      "entity-name": "Money Technology Ltd",
      "corporation-type": "private-limited-company",
      "entity-registration-number": "91824539",
      "date-of-incorporation": "2017-06-01",
      "building-number": "184",
      "city": "London",
      "street-name": "Argyle Street",
      "postal-code": "EC2V 9AN",
      "country-code": "GB"
    },
    {
      "claim-type": "director",
      "legal-person-url": "/v0/legal-persons/lp.njk7tIWvQJGPEFIdDmS9yQ"
    },
    {
      "claim-type": "person-with-significant-control",
      "legal-person-url": "/v0/legal-persons/lp.njk7tIWvQJGPEFIdDmS9yQ",
      "ownership-percent": "10"
    }
  ]
}'
info

An individual legal person can be both a director and a PSC for the same company. An individual legal person can also be a director and/or a PSC for multiple companies.

2. Choose your workflow​

Once you've created a legal-person representing your customer, you need choose your workflow - this determines the specific set of verification checks to be run on the customer. If your organisation already has predefined workflows, you can see them by querying organization-workflows-url, as shown below.

curl "https://api.griffin.sh/v0/organizations/${ORGANIZATION_ID}/workflows" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

In sandbox mode, you can choose from a standard set of sample workflows.

{
  "workflows": [
    {
      "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "Sample Workflow",
      "legal-person-type": "corporation"
    },
    {
      "workflow-url": "/v0/workflows/wf.G3yYmojQV32I814_5JLTEQ",
      "display-name": "Sample Individual Workflow",
      "legal-person-type": "individual"
    },
    {
      "workflow-url": "/v0/workflows/wf.W1NwgL6sXCmB3u9cPiJoKQ",
      "display-name": "Sample Sole Trader Workflow",
      "legal-person-type": "individual"
    }
  ]
}

Save the relevant workflow-url to use in the next step.

3. Run the verification​

Now you can submit the legal person representing your customer 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 is 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 example verification below is created against an individual legal person, but the process is the same for a corporation legal person.

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.W1NwgL6sXCmB3u9cPiJoKQ"}'

The response will look like this. You can use the verification-url for monitoring.

{
  "created-at": "2022-08-15T10:47:51.959Z",
  "display-name": "FLORES, Julia",
  "legal-person-type": "individual",
  "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.W1NwgL6sXCmB3u9cPiJoKQ"
}

Monitoring the verification​

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, as shown in the example.

{
  "created-at": "2022-08-15T10:47:51.959Z",
  "display-name": "FLORES, Julia",
  "legal-person-type": "individual",
  "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.W1NwgL6sXCmB3u9cPiJoKQ"
}

4. Make an onboarding decision​

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

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

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

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": "No red flags here",
      "decision-user-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
      "created-at": "2022-08-15T10:47:51.959Z"
    },
  "display-name": "FLORES, Julia",
  "application-status": "accepted",
  "status-changed-at": "2019-08-24T14:15:22Z",
  "created-at": "2019-08-24T14:15:22Z",
  ...
}

You can also set or change the decision-outcome as shown below.

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": "Results indicate this customer is within our risk threshold",
  "decision-outcome": "accepted",
  "verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA"
}'