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": "construction-worker",
      "industry-of-occupation": "property-and-construction"
    },
    {
      "claim-type": "individual-income",
      "income": {
        "value": "85000.00",
        "currency": "GBP"
      }
    },
    {
      "claim-type": "nationality",
      "nationality": "GB"
    },
    {
      "claim-type": "tax-residency",
      "tax-residency": "GB"
    },
    {
      "claim-type": "individual-purposes-of-account",
      "individual-purposes-of-account": ["everyday-spending"]
    },
    {
      "claim-type": "individual-sources-of-funds",
      "individual-sources-of-funds": ["savings"]
    },
    {
      "claim-type": "cash-payments",
      "cash-payments?": false
    },
    {
      "claim-type": "initial-deposit",
      "initial-deposit": {
        "currency": "GBP",
        "value": "100.00"
      }
    },
    {
      "claim-type": "international-payments-countries",
      "international-payments-countries": ["FR"]
    }
  ]
}'

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' \
  -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.

To find out the ID&V links, you can poll the verification-resources-urluntil they become available. You can also leverage webhooks and listen for the verification-resource-created|updated events, emitted once the ID&V links are 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"
  }
}

The idv-check-status begins in a pending state and transitions to one of three final states: complete, errored, or expired.

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

Updating customer information​

This section applies to both Verify and Reliance Onboarding.

For any customer information that has changed, you can re-submit just the claim information that needs updating and the checks associated with that claim will be re-run. These checks will re-run when another verification is run.

You can submit the updated claim information for each legal persons using:

 POST https://api.griffin.com/v0/legal-persons/{legal-person-id}/claims

Once you have updated a claim you can fetch a list of unverified claims using the filter:

GET https://api.griffin.com/v0/legal-persons/{legal-person-id}/claims?filter[verification-status][eq]=unverified

The verification-status will change from unverified to verified when it has successfully been used as part of an accepted verification.

info

A verified claim has been used by an accepted verification. An unverified claim is when a verification hasn’t been run on a claim, or a verification resulted in a declined or errored decision.

You will need to run a new verification after you have updated claims by using:

 POST https://api.griffin.com/v0/legal-persons/{legal-person-id}/verifications
 
 {
    "workflow-url": "{workflow-id}"
 }