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. Inspect the risk assessment outcomes (limited companies only)
  5. 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 (company)​

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.com/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
  • tax residency
  • nationality
  • email address
  • mobile number

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.com/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"
    },
    {
      "claim-type": "tax-residency",
      "tax-residency": "GB"
    },
    {
      "claim-type": "nationality",
      "nationality": "GB"
    },
    {
      "claim-type": "mobile-number",
      "mobile-number": "+440000000000"
    }  
  ]
}'

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.

You will also need to submit the following information about the company:

  • telephone number
  • business description
  • tax residency
  • list of non-UK countries where they operate (leave empty if not applicable).
  • list of non-UK countries where their accounts will send and receive payments from (leave empty if not applicable).
  • estimated annual turnover
  • initial deposit source
  • website
  • email address
  • source(s) of funds
  • purpose(s) of account
  • tax identification number
  • SIC codes
curl "https://api.griffin.com/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": "company-telephone-number",
      "telephone-number": "+440000000000"
    },
    {
      "claim-type": "business-description",
      "business-description": "a business description"
    },
    {
      "claim-type": "tax-residency",
      "tax-residency": "GB"
    },
    {
      "claim-type": "international-operations-countries",
      "international-operations-countries": []
    },
    {
      "claim-type": "international-payments-countries",
      "international-payments-countries": []
    },
    {
      "claim-type": "annual-turnover",
      "annual-turnover": {
        "value": "5000.00",
        "currency": "GBP"
      }
    },
    {
      "claim-type": "initial-deposit",
      "initial-deposit": {
        "value": "1000.00",
        "currency": "GBP"
      }
    },
    {
      "claim-type": "company-website",
      "website-url": "https://www.griffin.com"
    },
    {
      "claim-type": "company-email-address",
      "email-address": "email@example.com"
    },
    {
      "claim-type": "sources-of-funds",
      "sources-of-funds": ["salary-or-bonus"]
    },
    {
      "claim-type": "purposes-of-account",
      "purposes-of-account": ["long-term-investment"]
    },
    {
      "claim-type": "tax-identification-number",
      "tax-identification-number": "01234567"
    },
    {
      "claim-type": "sic-codes",
      "sic-codes": ["01110"]
    },
    {
      "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.com/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": "LTD Company",
      "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.

info

Some workflows contain ID&V checks. When you run a workflow to onboard a company in live mode, it will trigger emails to the identified directors and PSCs, asking them to complete ID&V by submitting a selfie and a photo of their ID. In sandbox mode, no external parties will be contacted, but you will receive a test version of the ID&V email. No selfies or ID photos are captured in sandbox mode and all ID&V results are mock-ups. Learn more about sandbox vs. live mode.

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.com/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.com/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. Inspect the risk assessment outcomes​

info

Right now, we only offer risk assessments for limited companies. Risk assessments for individuals and sole traders are coming soon!

Once the verification reaches checks-complete, we run a detailed risk assessment and produce an overall risk rating.

You can access these by navigating to the verification-risk-assessments-url.

info

Some checks in a workflow can trigger an early termination of the verification. In that case, the verification will change to checks-declined and we will not run a risk assessment.

curl 'https://api.griffin.com/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA/risk-assessments' -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"
{
    "overall-risk-assessment-outcomes": [
        {
            "legal-person-url": "/v0/legal-persons/lp.G6j5L7EjTB2KEpFKPCwrdQ",
            "overall-risk-rating": "low-risk",
            "overall-risk-score": {
                "risk-score-type": "number",
                "risk-score-value": 5
            },
            "risk-assessment-outcomes": [
                {
                    "legal-person-url": "/v0/legal-persons/lp.G6j5L7EjTB2KEpFKPCwrdQ",
                    "risk-factor-name": "Active directors",
                    "risk-rating": "low-risk",
                    "risk-score": {
                        "risk-score-type": "number",
                        "risk-score-value": 0
                    }
                },
                {
                    "legal-person-url": "/v0/legal-persons/lp.G6j5L7EjTB2KEpFKPCwrdQ",
                    "risk-factor-name": "Company sanctions",
                    "risk-rating": "low-risk",
                    "risk-score": {
                        "risk-score-type": "number",
                        "risk-score-value": 0
                    }
                },
                {
                    "legal-person-url": "/v0/legal-persons/lp.ZKiyGS80S1OkTAaOCjxmxg",
                    "risk-factor-name": "Individual tax residency",
                    "risk-rating": "low-risk",
                    "risk-score": {
                        "risk-score-type": "number",
                        "risk-score-value": 0
                    }
                }
              ...
            ]
        }
    ],
    "links": {
        "prev": null,
        "next": null
    }
}

5. Make an onboarding decision​

Once we have the risk assessment outcomes, the application-status will change to accepted or declined depending on the overall risk rating (or referred if a manual review is required).

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

curl 'https://api.griffin.com/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.com/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"
}'