Onboard a sole trader

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.

Information	Claim
Business name (leave empty if not applicable)	`business-name`
Trading name (if different from name)	`trading-name`
Business address	`business-address`
Trading address (if different from business address)	`trading-address`
Business owner	`business-owner`
Business phone number	`business-telephone-number`
Email address	`business-email-address`
Website	`business-website`
Business start date	`business-start-date`
Annual turnover	`annual-turnover`
VAT registration	`vat-registration`
Business tax residency/ies	`tax-residencies`
Tax identifier number/s (optional for UK only if turnover is under £90k)	`tax-identification-numbers-by-country`
Business trading name (if different from business name)	`trading-name`
Industry	`business-industry`
SIC code	`sic-codes`
Business size	`business-size`
Employee count*	`number-of-employees`
Balance sheet size*	`balance-sheet-size`
International operations	`international-operations-countries`
↓ Individual information ↓
Full name	`individual-identity`
Date of birth	`individual-identity`
Email address	`contact-details`
Address	`individual-residence`
Phone number	`mobile-number`
Nationality	`nationality`
Tax residency/ies	`tax-residencies`
US citizen confirmation	`us-citizen`
Tax identifier number/s	`tax-identification-numbers-by-country`
↓ Use of account ↓
Purpose(s) of account	`purposes-of-account`
Source(s) of funds	`individual-sources-of-funds`
Initial deposit value	`initial-deposit`
International payment locations	`international-payments-countries`
Cash payments	`cash-payments`

*Requested but not required

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-residencies",
      "tax-residencies": [
        "GB",
        "US"
      ]
    },
    {
      "claim-type": "tax-identification-numbers-by-country",
      "tins-by-country": {
        "GB": [
          "1234 5678 901"
        ],
        "US": [
          "123-45-6789",
          "12-3456789"
        ]
      }
    },
    {
      "claim-type": "us-citizen",
      "us-citizen?": false
    },
    {
      "claim-type": "business-industry",
      "business-industry": "creative-industries",
      "line-of-business": "photography"
    },
    {
      "claim-type": "sic-codes",
      "sic-codes": ["74209"]
    },
    {
      "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": "business-size",
      "business-size": "small"
    },
    {
      "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.

Information	Claim
Number of properties under management	`managed-properties`
% of commercial properties managed	`commercial-property-ratio`
HMO verification	`hmo-license`
HMRC status and registration number	`hmrc-register`
CMP registration status and the scheme name/authority	`client-money-protection-scheme`

2. Run the verification

2.1 Retrieve your workflows

If your onboarding a customer for the first time you will need to retrieve your workflows in order to submit the verification. Retrieve and cache your workflow 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.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "Sole Trader - Account Owners",
      "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 - Account Owners" workflow when onboarding individuals.

2.2 Submit

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.Ul-1r4gRWfOFxHJsHWghcA"}'

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

{
  "created-at": "2022-08-15T10:47:51.959Z",
  "display-name": "Money Technology Ltd.",
  "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"
}

3. Send ID&V request

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.

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.

Embedding the ID&V flow in your web/mobile app

For a better user experience, you can embed Veriff's ID&V flow directly within your application instead of redirecting users to an external page. Veriff provides SDKs for web, iOS, and Android that accept the session URL (the idv-check-url generated above) and render the verification flow natively in your app.

For detailed integration instructions, code examples, and platform-specific guidance, see Veriff's SDK documentation.

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.

1. Capture the sole trader’s information​

1.2 Letting agents​

2. Run the verification​

2.1 Retrieve your workflows​

2.2 Submit​

3. Send ID&V request​

Embedding the ID&V flow in your web/mobile app​

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​

1. Capture the sole trader’s information

1.2 Letting agents

2. Run the verification

2.1 Retrieve your workflows

2.2 Submit

3. Send ID&V request

Embedding the ID&V flow in your web/mobile app

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