Onboard a limited company

There are four steps to onboarding a company with Verify.

Capture the company information
Run the verification
Send ID&V requests to directors and PSCs
View the risk assessment outcome and onboarding decision

info

Right now, Verify only supports limited companies registered in the UK.

Verify does support onboarding of companies where directors and PSCs who are individuals are residents in the following jurisdictions: 🇬🇧 UK, 🇪🇺 European Union, 🇦🇪 United Arab Emirates, 🇭🇰 Hong Kong, 🇦🇺 Australia, 🇸🇬 Singapore, 🇺🇸 United States of America, and 🇲🇾 Malaysia.

See here for details on claim requirements for addresses outside the UK.

1. Capture the company information

This is all the information required in the steps below to onboard a LTD company.

Information	Claim
Business name	`uk-company-register`
Corporation type	`uk-company-register`
Date of incorporation	`uk-company-register`
Company status	`uk-company-register`
Confirmation statement overdue	`uk-company-register`
Date of latest confirmation statement	`uk-company-register`
Accounts overdue	`uk-company-register`
Date of latest accounts	`uk-company-register`
Company address	`uk-company-register`
SIC code(s)	`sic-codes`
Business size	`business-size`
Website	`company-website`
Email address	`uk-company-register`
Telephone number	`uk-company-register`
Tax residency/ies	`tax-residencies`
Tax identification number/s	`tax-identification-numbers-by-country`
International operations (leave empty if not applicable)	`international-operations-countries`
Number of employees*	`number-of-employees`
Balance sheet size*	`balance-sheet-size`
Estimated annual turnover	`annual-turnover`
Business description	`business-description`
Companies house url (for the officer)	`uk-company-register`
↓ Director & PSC info ↓
Full name	`individual-identity`
Date of birth	`individual-identity`
Email address	`contact-details`
Address	`individual-residence`
Mobile number	`contact-details`
Nationality	`nationality`
Tax residency/ies	`tax-residencies`
US citizen confirmation	`us-citizen`
Tax identifier number/s	`tax-identification-numbers-by-country`
Natures of control (director or PSC)	`person-with-significant-control` or `director`
Ownership of shares (PSC only)	`person-with-significant-control`
↓ 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

1.1 Look up the Companies House record

info

This step is optional. If you already know all of the required data you can jump to step 1.3

Get the unique 8-digit company number for the company you want to onboard, and use it to query Companies House.

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 people with significant control (PSCs).

{
  "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": {
    "building-number": "12",
    "street-name": "Argyle Street",
    "city": "London",
    "postal-code": "EC2V 9AN",
    "country-code": "GB"
  },
  "sic-codes": [
    "01110"
  ],
  "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 Create legal persons for directors and PSCs

In the API, the company, its directors, and its PSCs are all represented as legal persons.

Create individual legal persons to represent the company’s directors and PSCs.

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

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 all their claims in one go, but you can also create a legal person and then add claims individually. For more detail on claims, see the API reference.

caution

An individual can be both a director and a PSC for the same company. In this case, you must not verify them twice. Create one individual legal person to represent them and use it for both the director and person-with-significant-control claims in the next step.

1.3 Create a legal person to represent the company

Create a corporation legal person to represent the company.

Use the information collected in step 1.2 to create a uk-company-register claim.

Use the director and person-with-significant-control claims to associate the relevant individual legal persons with the company.

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

telephone number
business description
business size
tax residency(ies)
list of non-UK countries where they operate (leave empty if not applicable)
list of non-UK countries their accounts will 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(s)
SIC codes
cash payments (i.e. will the account receive payments from accounts that are funded, in full or in part, by cash deposits?)

As above, each of these data points represent one claim. You can create the legal person and add their claims as shown below.

At this point you will also need to submit the remaining information about the company as shown in step 1.1:

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-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": "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": "sic-codes",
      "sic-codes": ["01110"]
    },
    {
      "claim-type": "business-size",
      "business-size": "medium"
    },
    {
      "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"
    },
    {
      "claim-type": "cash-payments",
      "cash-payments?": false
    }
  ]
}'

1.4 Letting agents and landlords

If the company you are onboarding is a letting agent or a landlord, you will also need to provide the following information. This is in addition to the claims listed in step 1.3.

Letting agents

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

Landlords

Information	Claim
Number of properties owned	`managed-properties`
What funds the landlord intends to receive into the account	`properties-origins-of-deposits`
HMO license	`hmo-license`
HMRC status and registration number	`hmrc-register`
Whether the properties owned are residential, commercial, holiday lets, or HMO	`property-types`
If they own commercial properties, what industries	`commercial-property-industries`

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": "LTD Company",
      "legal-person-type": "corporation"
    },
  ]
}

2.2 Submit

Submit the corporation 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": "corporation",
  "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 requests to directors and PSCs

info

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

The company’s directors and PSCs 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 the relevant directors and PSCs 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.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": "2019-08-24",
      "display-name": "string",
      "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA"
    },
  ],
  "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-11T10:47:51.959Z",
  "display-name": "Money Technology Ltd.",
  "legal-person-type": "corporation",
  "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"
}

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-08-15T10:47:51.959Z"    
        },  
            "display-name": "Money Technology Ltd.",  
            "application-status": "accepted",  
            "status-changed-at": "2024-08-24T14:15:22Z",  
            "created-at": "2024-08-24T14:15:22Z",  
            ...
    }

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

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

There are four steps to onboarding a company with Verify.​

1. Capture the company information​

1.1 Look up the Companies House record​

1.2 Create legal persons for directors and PSCs​

1.3 Create a legal person to represent the company​

1.4 Letting agents and landlords​

2. Run the verification​

2.1 Retrieve your workflows​

2.2 Submit​

3. Send ID&V requests to directors and PSCs​

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​

There are four steps to onboarding a company with Verify.

1. Capture the company information

1.1 Look up the Companies House record

1.2 Create legal persons for directors and PSCs

1.3 Create a legal person to represent the company

1.4 Letting agents and landlords

2. Run the verification

2.1 Retrieve your workflows

2.2 Submit

3. Send ID&V requests to directors and PSCs

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