Onboard a sole trader

Before you can hold money in a Griffin bank account on behalf of a sole trader, 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.

Understanding Workflows

Before diving into the onboarding process, it's important to understand workflows. Each organization is assigned several workflows, which determine the specific verification checks to run based on customer type.

About Workflows

Your organization will have a set of predefined workflows with unique IDs
These workflow IDs remain constant and can be cached after initial retrieval
Different workflows exist for different customer types (e.g. standard sole trader, landlords)
You simply select the appropriate workflow ID when running a verification

Retrieving Your Workflows

You only need to retrieve your workflows once (or when you have new workflows added) and can cache the IDs:

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

Example response:

{
  "workflows": [
    {
      "workflow-url": "/v0/workflows/wf.W1NwgL6sXCmB3u9cPiJoKQ",
      "display-name": "Sole Trader Default",
      "legal-person-type": "individual"
    },
    {
      "workflow-url": "/v0/workflows/wf.W1NwgL6sXCmB3u9cPiJoKQ",
      "display-name": "Sole Trader Property",
      "legal-person-type": "individual"
    }
  ]
}

tip

In your implementation, store these workflow IDs and match them to the appropriate customer type. For example, use the "Sole Trader Default" workflow when onboarding sole traders.

Verify

There are four steps to onboarding a sole trader with Verify.

Capture the sole trader’s information
Run the verification
Send the ID&V request
View the verification outcome and onboarding decision

info

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

1. Capture the sole trader’s information

You will need the following information about the sole trader and their business.

Individual information:

full name and date of birth
nationality
email address
residential address
phone number
tax residency

Business information:

industry
business name (leave empty if not applicable)
business address
business owner
business phone number
email address
website
business start date
annual turnover
VAT registration
tax identification number (optional if turnover is under £90k)
business trading name (if different from business name)
business trading address (if different from business address)
list of non-UK countries where they operate (leave empty if not applicable)

Account use:

purpose(s) of account
source(s) of funds
value of initial deposit
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 sole trader 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": "Floyd Black Photography",
  "legal-person-type": "individual",
  "claims": [
    {
      "claim-type": "individual-identity",
      "given-name": "Floyd",
      "surname": "Black",
      "date-of-birth": "1985-12-05"
    },
    {
      "claim-type": "contact-details",
      "email-address": "floyd@fbphotography.co.uk"
    },
    {
      "claim-type": "individual-residence",
      "street-name": "Lens Avenue",
      "city": "Snap City",
      "postal-code": "TE1 2ST",
      "country-code": "GB",
      "building-number": "34"
    },
    {
      "claim-type": "mobile-number",
      "mobile-number": "+442012345678"
    },
    {
      "claim-type": "nationality",
      "nationality": "GB"
    },
    {
      "claim-type": "tax-residency",
      "tax-residency": "GB"
    },
    {
      "claim-type": "business-industry",
      "business-industry": "creative-industries",
      "line-of-business": "photography"
    },
    {
      "claim-type": "business-name",
      "business-name": "Floyd Black Photography"
    },
    {
      "claim-type": "business-address",
      "business-address": {
        "street-name": "Lens Avenue",
        "city": "Snap City",
        "postal-code": "TE1 2ST",
        "country-code": "GB",
        "building-number": "34"
      }
    },
    {
      "claim-type": "business-owner",
      "business-owner?": true
    },
    {
      "claim-type": "business-telephone-number",
      "telephone-number": "+442087654321"
    },
    {
      "claim-type": "business-email-address",
      "email-address": "floyd@fbphotography.co.uk"
    },
    {
      "claim-type": "business-website",
      "website-url": "https://www.fbphotography.co.uk"
    },
    {
      "claim-type": "business-start-date",
      "business-start-date": "2021-03-26"
    },
    {
      "claim-type": "business-description",
      "business-description": "Drone photography of outdoor events and concerts"
    },
    {
      "claim-type": "annual-turnover",
      "annual-turnover": {
        "value": "66000.00",
        "currency": "GBP"
      }
    },
    {
      "claim-type": "tax-identification-number",
      "tax-identification-number": "01234567"
    },
    {
      "claim-type": "international-operations-countries",
      "international-operations-countries": []
    },
    {
      "claim-type": "international-payments-countries",
      "international-payments-countries": []
    },
    {
      "claim-type": "individual-purposes-of-account",
      "individual-purposes-of-account": ["business-expenses"]
      ]
    },
    {
      "claim-type": "individual-sources-of-funds",
      "individual-sources-of-funds": ["business-income"]
    },
    {
      "claim-type": "initial-deposit",
      "initial-deposit": {
        "value": "1000.00",
        "currency": "GBP"
      }
    },
    {
      "claim-type": "vat-registration",
      "vat-registration?": true
    },
    {
      "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 Letting agents

If the sole trader you are onboarding is a letting agent, you will need to include the following information, in addition to the claims listed above.

Number of properties under management
% of commercial properties managed
HMO verification
HMRC status and registration number
CMP registration status and the scheme name/authority

2. 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 later.

{
  "created-at": "2024-02-10T10:47:51.959Z",
  "display-name": "Floyd Black Photography",
  "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.W1NwgL6sXCmB3u9cPiJoKQ"
}

3. Send ID&V request

The sole trader 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 their ID 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-url until 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.IGxlZ2FsLXBlcnNvbi1pZA",
  "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-17",
      "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.

4. View the verification outcome and onboarding decision

Verification Status

The verification has successfully completed when verification-status reaches checks-complete. You can track this by:

Polling the verification-url
Listening for verification-updated webhook events

Example response:

{
  "created-at": "2024-02-10T10:47:51.959Z",
  "display-name": "Floyd Black Photography",
  "legal-person-type": "individual",
  "legal-person-url": "/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45",
  "risk-rating": "low-risk",
  "updated-at": "2022-02-14T10:48:03.215Z",
  "verification-status": "checks-complete",
  "verification-url": "/v0/verifications/vn.BhpS_dCqFKRYXa8d457fgA",
  "workflow-url": "/v0/workflows/wf.G3yYmojQV32I814_5JLTEQ"
}

Verification Statuses Explained

Status	Description
`pending`	Verification has been created but processing has not yet begun
`in-progress`	Verification checks are actively being performed
`failed`	An internal system error has occurred during verification
`checks-declined`	Verification was terminated early due to failing one or more workflow checks
`checks-complete`	Verification has successfully completed all required checks

Verification Status Flow

Decision Process

After reaching checks-complete, the system will either:

Generate an automated decision
Refer the application for manual review (followed by a manual decision)

Tracking Decisions

Monitor decisions by:

Polling the legal-person-decisions-url endpoint
Listening for decision-created webhook events

Application Status & Decision Flow

In context

Both the verification status and the decisions can be seen in context on the legal person entity.

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-02-14T14:15:22Z"
  },
  "display-name": "Floyd Black Photography",
  "application-status": "accepted",
  "status-changed-at": "2024-02-14T14:15:22Z",
  "created-at": "2024-02-10T14:15:22Z",
  ...
}

Once you have an accepted decision, you're good to go 🎉

What's next? Open an account! See here to get started.

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 sole traders 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 a sole trader using Reliance.

Choose your workflow
Capture the sole trader’s information
Submit an application
Receive a decision

1. Choose your workflow

Find the Reliance Sole Trader 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 Sole Trader",
      "legal-person-type": "individual"
    }
  ]
}

2. Capture the sole trader’s information

You will need to provide the following information about the sole trader

Individual’s full name
Business name
Business type (always sole trader)
Residential address
Date of birth

2.1 Attesting to verification

In addition to submitting the above information about the sole trader, 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.Ul-1r4gRWfOFxHJsHWghcA",
  "subject-profile": {
    "display-name": "Floyd Black Photography",
    "claims": [
      {
        "claim-type": "individual-identity",
        "given-name": "Floyd",
        "surname": "Black",
        "date-of-birth": "1985-12-05"
      },
      {
        "claim-type": "individual-residence",
        "street-name": "Lens Avenue",
        "city": "Snap City",
        "postal-code": "TE1 2ST",
        "country-code": "GB",
        "building-number": "34"
      },
      {
        "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-02-10T14: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-02-10T14: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-02-10T14: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}"
 }

Understanding Workflows​

About Workflows​

Retrieving Your Workflows​

Verify​

1. Capture the sole trader’s information​

1.2 Letting agents​

2. Run the verification​

3. Send ID&V request​

4. View the verification outcome and onboarding decision​

Verification Status​

Verification Statuses Explained​

Verification Status Flow​

Decision Process​

Tracking Decisions​

Application Status & Decision Flow​

In context​

Reliance onboarding​

1. Choose your workflow​

2. Capture the sole trader’s information​

2.1 Attesting to verification​

3. Submit an application​

3.1. Monitoring the application​

4. Receive a decision​

Updating customer information​

Understanding Workflows

About Workflows

Retrieving Your Workflows

Verify

1. Capture the sole trader’s information

1.2 Letting agents

2. Run the verification

3. Send ID&V request

4. View the verification outcome and onboarding decision

Verification Status

Verification Statuses Explained

Verification Status Flow

Decision Process

Tracking Decisions

Application Status & Decision Flow

In context

Reliance onboarding

1. Choose your workflow

2. Capture the sole trader’s information

2.1 Attesting to verification

3. Submit an application

3.1. Monitoring the application

4. Receive a decision

Updating customer information