Skip to main content

Onboard a limited company

To onboard a limited company, you will need to capture information about the company itself and also verify the identities of any company directors or people with significant control (PSCs).

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.

Learn more about Verify vs Reliance

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 limited companies, letting agents)
  • 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.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "LTD Company",
      "legal-person-type": "corporation"
    },
    {
      "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "LTD Company Property",
      "legal-person-type": "corporation"
    },
    {
      "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "LTD Company Landlord",
      "legal-person-type": "corporation"
    }
  ]
}
tip

In your implementation, store these workflow IDs and match them to the appropriate customer type. For example, use the "LTD Company" workflow when onboarding limited companies.

Verify​

There are four steps to onboarding a company with Verify.

  1. Capture the company information
  2. Run the verification
  3. Send ID&V requests to directors and PSCs
  4. View the risk assessment outcome and onboarding decision
info

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

1. Capture the company information​

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

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

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. You will need their:

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

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-residency",
      "tax-residency": "GB"
    },
    {
      "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.

Create a corporation legal person to represent the company.

Use the information collected in step 1.1 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
  • tax residency
  • 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
  • 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.

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-residency",
      "tax-residency": "GB"
    },
    {
      "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": "tax-identification-number",
      "tax-identification-number": "01234567"
    },
    {
      "claim-type": "sic-codes",
      "sic-codes": ["01110"]
    },
    {
      "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 agentsLandlords
Number of properties under managementNumber of properties owned
Origins of deposits (e.g. tenant-rental-income)What funds the landlord intends to receive into the account
HMO verificationHMO verification
HMRC status and registration numberHMRC status and registration number
CMP registration status and the scheme name/authorityWhether properties owned are residential, commercial, holiday lets, or HMO.
% of commercial properties managedIf commercial properties, what industries

2. Run the verification​

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​

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.

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.

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​
StatusDescription
pendingVerification has been created but processing has not yet begun
in-progressVerification checks are actively being performed
failedAn internal system error has occurred during verification
checks-declinedVerification was terminated early due to failing one or more workflow checks
checks-completeVerification 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.

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 limited companies 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 company using Reliance.

  1. Choose your workflow
  2. Capture the company information
  3. Submit the application
  4. Receive a decision

1. Choose your workflow​

Find the Reliance Ltd Company workflow by querying organization-workflows-url, as shown below. 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 LTD Company",
      "legal-person-type": "corporation"
    },
  ]
}

2. Capture the company information​

You will need to provide the following information about the company, its directors and people with significant control (PSCs). PSCs are also sometimes called beneficial owners.

  • Company name
  • Company registration number
  • Business type
  • Company trading address
  • Company registered address
  • Directors and PSCs:
    • Full name
    • Address
    • Date of birth

2.1 Attesting to verification​

In addition to submitting the above information about the company, you must also attest that you have verified both the company information and the identities of the directors and PSCs. 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 company you are onboarding.

  • uk-company-register
  • trading-address
  • reliance-verification

You will need to provide the following claims for each related profile, which represents a director or PSC of the company.

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

Here is an example application:

{
  "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
  "subject-profile": {
    "display-name": "Money Technology Ltd",
    "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": "trading-address",
        "trading-address": {
          "building-name": "Tower A",
          "building-number": "12",
          "street-name": "High Street",
          "city": "London",
          "postal-code": "TE1 2ST",
          "country-code": "GB"
        }
      },
      {
         "claim-type": "reliance-verification",
         "reliance-verification-methods": ["manual-biometric"],
         "reliance-verification-standard": "jmlsg"
      }
    ]
  },
  "related-profiles": [
    {
      "display-name": "JOHNSON, Talia",
      "subject-association": {
        "director": {}
      },
      "claims": [
        {
          "claim-type": "individual-identity",
          "date-of-birth": "1982-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": "reliance-verification",
         "reliance-verification-methods": ["manual-biometric"],
         "reliance-verification-standard": "jmlsg"
        }
      ]
    },
    {
      "display-name": "KLEIN, Monica",
      "subject-association": {
        "psc": {}
      },
      "claims": [
        {
          "claim-type": "individual-identity",
          "date-of-birth": "1963-02-02",
          "given-name": "Monica",
          "surname": "Klein"
        },
        {
          "claim-type": "individual-residence",
          "building-number": "19",
          "street-name": "Example Street",
          "city": "Test Town",
          "postal-code": "TE1 2ST",
          "country-code": "GB"
        },
        {
          "claim-type": "reliance-verification",
          "reliance-verification-methods": ["manual-biometric", "manual-document"],
          "reliance-verification-standard": "jmlsg"
        }
      ]
    }
  ]
}

If a director is also a PSC, you should add both roles on the subject-association parameter, as shown below:

{
  "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
  "subject-profile": {...},
  "related-profiles": [
    {
      "display-name": "JOHNSON, Talia",
      "subject-association": {
        "director": {},
        "psc": {}
      },
      "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": "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 and related profiles 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": "2019-08-24T14:15:22Z",
  "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
  "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": "2019-08-24T14:15:22Z",
  "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
  "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": "2019-08-24T14:15:22Z",
  "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
  "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}"
 }

If a director or PSC has changed you can remove them from the application using

DELETE https://api.griffin.com/v0/claims/{claim-id}

A successful response will give you a 204 response code.

You can then add a new director or PSC using the claims endpoint as usual.