Skip to main content

Onboard an individual

Before you can hold money in a Griffin bank account on behalf of an individual, you will need to onboard them.

This process will look different, depending on whether you are using:

  • Verify, our automated onboarding product, or
  • Reliance onboarding, when you create and submit application on behalf of your customer using information you have already collected and verified.

Verify​

There are five steps to onboarding an individual with Verify.

  1. Capture the individual’s information
  2. Choose your workflow
  3. Run the verification
  4. Send the ID&V request
  5. View the risk assessment outcome and onboarding decision
info

Verify supports onboarding of individuals from the UK and from the Crown Dependencies (Jersey, Guernsey, and Isle of Man).

1. Capture the individual’s information​

You will need the following information about the individual:

  • full name and date of birth
  • nationality
  • email address
  • residential address
  • phone number
  • employment status, occupation, and industry
  • annual income
  • tax residency
  • purpose(s) of account
  • source(s) of funds
  • list of non-UK countries where their accounts will receive payments from (leave empty if not applicable)
  • cash payments (i.e. will the account receive payments from accounts that are funded, in full or in part, by cash deposits?)

In the API, your customer is represented as a legal person, and each of the data points above represent one claim about them. Create an individual legal person to represent the customer and then add claims about them, 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": "DAVIS, Henry",
  "legal-person-type": "individual",
  "claims": [
    {
      "claim-type": "individual-identity",
      "given-name": "Henry",
      "surname": "Davis",
      "date-of-birth": "1991-05-10"
    },
    {
      "claim-type": "contact-details",
      "email-address": "henrydavis@example.com"
    },
    {
      "claim-type": "individual-residence",
      "street-name": "Example Street",
      "city": "Test Town",
      "postal-code": "TE1 2ST",
      "country-code": "GB",
      "building-number": "19"
    },
    {
      "claim-type": "mobile-number",
      "mobile-number": "+442012345678"
    },
    {
      "claim-type": "employment",
      "employment-status": "employed",
      "occupation": "sales",
      "industry-of-occupation": "construction"
    },
    {
      "claim-type": "individual-income",
      "income": {
        "value": "85000.00",
        "currency": "GBP"
      }
    },
    {
      "claim-type": "nationality",
      "country-code": "GB"
    },
    {
      "claim-type": "tax-residency",
      "tax-residency": "GB"
    },
    {
      "claim-type": "individual-purposes-of-account",
      "purposes-of-account": ["everyday-spending"]
    },
    {
      "claim-type": "individual-sources-of-funds",
      "sources-of-funds": ["savings"]
    },
    {
      "claim-type": "cash-payments",
      "cash-payments?": false
    }
  ]
}'

A successful response will display the URL for the newly created legal person (e.g./v0/legal-persons/lp.njk7tIWvQJGPEFIdDmS9yQ) in the response's Location header and in the response body. Save this URL for the next step.

info

In this example, you create the legal person and their claims in one go, but you can also create a legal person first and then add claims individually. For more detail on claims, see the API reference.

1.2 Landlords​

If the individual you are onboarding is a landlord, you will need to include the following information, in addition to the claims listed above.

  • Number of properties owned
  • What funds the landlord intends to receive into the account
  • HMO verification
  • Whether the properties owned are residential, commercial, holiday lets, or HMO
  • If they own commercial properties, what industries

2. Choose your workflow​

Find the correct workflow by querying organization-workflows-url, as shown below. Workflows determine the specific set of verification checks to be run on the legal person. Grab the workflow-url to use in the next step.

curl "https://api.griffin.com/v0/organizations/${ORGANIZATION_ID}/workflows" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"
{
  "workflows": [
    {
      "workflow-url": "/v0/workflows/wf.G3yYmojQV32I814_5JLTEQ",
      "display-name": "Individual Default",
      "legal-person-type": "individual"
    },
    {
      "workflow-url": "/v0/workflows/wf.G3yYmojQV32I814_5JLTEQ",
      "display-name": "Individual Landlord",
      "legal-person-type": "individual"
    }
  ]
}

3. Run the verification​

Submit the individual legal person for verification, as shown below.

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

A successful response will look like this. Grab the verification-url for monitoring.

{
  "created-at": "2024-02-10T10:47:51.959Z",
  "display-name": "DAVIS, Henry",
  "legal-person-type": "individual",
  "legal-person-url": "/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
  "updated-at": "2024-02-10T10:47:51.959Z",
  "verification-status": "pending",
  "verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA",
  "workflow-url": "/v0/workflows/wf.G3yYmojQV32I814_5JLTEQ"
}

3.1 Monitoring the verification​

To monitor the verification either poll the verification-url or create a webhook and listen for the verification-created and verification-updated events.

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

The verification starts in a pending state. From there, it may transition to in-progress and then to checks-complete.

Once the verification reaches checks-complete, a decision is created.

The verification may also transition to failed if there is an error when communicating with our verification providers.

4. Send ID&V request​

The individual will need to complete an identity and verification (ID&V) check before the verification can be completed. This involves submitting a selfie and a photo of a valid identity document to Veriff, our ID&V partner.

Get the ID&V link from idv-check-url within /verifications/<:verification-id>/resources, as shown below. You will need to share this with your customer so they can complete ID&V.

Poll the verification-url to get notified of when the link is available.

{
"verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  "legal-person-url": "/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
  "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  "verification-resources": [
    {
      "verification-resource-type": "idv-check",
      "verification-resource-id": "a87ef592-c300-43f2-84f9-005120592392",
      "idv-check-status": "pending",
      "idv-check-url": "IDV.check.url",
      "idv-check-expires-at": "2024-02-16",
      "display-name": "string",
      "legal-person-url": "/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45"
    },
  ],
  "links": {
    "prev": "string",
    "next": "string"
  }
}
info

In sandbox, no selfies or ID photos are captured and all ID&V results are mock-ups. Learn more about sandbox vs. live mode.

5. View the risk assessment outcome and onboarding decision​

The processing is finished when the verification-status reaches checks-complete, as shown in the example.

{
  "created-at": "2024-02-11T10:47:51.959Z",
  "display-name": "DAVIS, Henry",
  "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.G3yYmojQV32I814_5JLTEQ"
}

Once the verification reaches checks-complete, you will be able to access a detailed risk assessment and an overall risk rating for the individual.

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.

You can access these by navigating to the verification-risk-assessments-url, as shown below.

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" : "/api/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
    "overall-risk-rating" : "low-risk",
    "overall-risk-score" : {
      "risk-score-type" : "number",
      "risk-score-value" : 0
    },
    "risk-assessment-outcomes" : [ {
      "legal-person-url" : "/api/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
      "risk-factor-name" : "Individual fraud",
      "risk-rating" : "low-risk",
      "risk-score" : {
        "risk-score-type" : "number",
        "risk-score-value" : 0
      },
      "requires-review?" : false
    }, {
      "legal-person-url" : "/api/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
      "risk-factor-name" : "KYC: individual age",
      "risk-rating" : "low-risk",
      "risk-score" : {
        "risk-score-type" : "number",
        "risk-score-value" : 0
      },
      "requires-review?" : false
    }
    ...]
  } ],
  "links" : {
    "prev" : null,
    "next" : null
  }
}

The application-status will change to accepted or declined depending on the overall risk rating (or referred if a manual review is required).

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": "2024-08-11T10:47:51.959Z"
  },
  "display-name": "DAVIS, Henry",
  "application-status": "accepted",
  "status-changed-at": "2024-02-11T10:47:51.959Z",
  "created-at": "2024-02-10T10:47:51.959Z",
  ...
}

Reliance onboarding​

note

Reliance onboarding is for regulated firms only. To check if you are eligible, speak to a member of our team.

Reliance onboarding allows you to carry out onboarding and complete all due diligence on your customers using your own tools and then provide us with the necessary information we require and an attestation of verification. We will periodically run assurance checks on your customer due diligence (CDD).

Once you’ve provided us with the information we need, we will run Politically Exposed Person (PEP) and Sanctions checks on your customer and, where applicable, an Immigration Act check.

info

You can submit applications for individuals based in the UK and in Crown Dependencies (Jersey, Guernsey, and Isle of Man).

caution

Only users with the compliance role can create and submit Reliance applications.

There are four steps to onboarding an individual using Reliance.

  1. Choose your workflow
  2. Capture the individual’s information
  3. Submit an application
  4. Receive a decision

1. Choose your workflow​

Find the Reliance Individual workflow by querying organization-workflows-url, as shown below. The workflow-url shown will be unique to your organization. Grab the workflow-url to use in the next step.

curl "https://api.griffin.com/v0/organizations/${ORGANIZATION_ID}/workflows" -H "Authorization: GriffinAPIKey$GRIFFIN_API_KEY"
{
  "workflows": [
    {
      "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "Reliance Individual",
      "legal-person-type": "individual"
    }
  ]
}

2. Capture the individual’s information​

You will need to provide the following information about the individual

  • Full name
  • Address
  • Date of birth

2.1 Attesting to verification​

In addition to submitting the above information about the individual, you must also attest that you have verified their identity. To do this, use the reliance-verification claim, and enter one or more of the following reliance-verification-methods:

  • electronic: the customer was verified using electronic sources e.g. Credit Reference Agency checks.
  • physical: the customer provided documentation in person.
  • manual-biometric: the customer’s government documentation has been cross-referenced with a selfie and verified by a third party.
  • manual-document: the customer supplied documentation e.g. a passport copy and address document.

You also must attest that the verification method used was in line with JMLSG standards.

3. Submit an application​

To submit an application, make a request to:

POST https://api.griffin.com/v0/organizations/{organization-id}/onboarding/applications

You will need to provide the following claims for the subject-profile, i.e. the profile of the individual you are onboarding.

  • individual-identity
  • individual-residence
  • reliance-verification

Here is an example application:

{
  "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  "subject-profile": {
    "display-name": "KLEIN, Monica",
    "claims": [
      {
        "claim-type": "individual-identity",
        "given-name": "Monica",
        "surname": "Klein",
        "date-of-birth": "1982-02-02"
      },
      {
        "claim-type": "individual-residence",
        "street-name": "Example Street",
        "city": "Test Town",
        "postal-code": "TE1 2ST",
        "country-code": "GB",
        "building-number": "19"
      },
      {
        "claim-type": "reliance-verification",
        "reliance-verification-methods": [
          "manual-biometric"
        ],
        "reliance-verification-standard": "jmlsg"
      }
    ]
  }
}

A successful response body looks like this:

{
  "onboarding-application-url": "/v0/onboarding/applications/oa.b25ib2FyZGluZy1hcHBsaQ",
  "onboarding-application-status": "submitted"
}

3.1. Monitoring the application​

To monitor the application status, either poll the onboarding-application-url or create a webhook and listen for the onboarding-application-created and onboarding-application-updated events.

Once an application has been submitted, it will register the subject profile and the status will update to processing. A legal-person-url and verification-url will be added to the application, as shown below:

{
  "onboarding-application-url": "/v0/onboarding/applications/oa.b25ib2FyZGluZy1hcHBsaQ",
  "created-at": "2024-08-24T14:15:22Z",
  "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  "onboarding-application-status": "processing",
  "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA"
}

4. Receive a decision​

When the onboarding-application-status moves to complete, a decision of accepted or declined will be added to the application.

A successful response body for a complete application that has been accepted looks like this:

{
  "onboarding-application-url": "/v0/onboarding/applications/oa.b25ib2FyZGluZy1hcHBsaQ",
  "created-at": "2024-08-24T14:15:22Z",
  "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  "onboarding-application-status": "complete",
  "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  "decision": "accepted"
}
info

Once the application is accepted, you can use the legal-person-url for the pooled account membership API.

If the verification process fails, the application status will update to errored. You can query the verification-url for more detail:

GET https://api.griffin.com/v0/verifications/{verification-id}

A body response for an errored application looks like this:

{
  "onboarding-application-url": "/v0/onboarding/applications/oa.b25ib2FyZGluZy1hcHBsaQ",
  "created-at": "2024-08-24T14:15:22Z",
  "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  "onboarding-application-status": "errored",
  "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA"
}