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.

Verify​

There are five steps to onboarding a company with Verify.

  1. Capture the company information
  2. Choose your workflow
  3. Run the verification
  4. Send ID&V requests to directors and PSCs
  5. 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​

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

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

{
  "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.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 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.

Poll the verification-url to get notified of when the link is 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"
  }
}
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.

5. View the risk assessment outcome and onboarding decision​

Once the verification reaches checks-complete, you will be able to access a detailed risk assessment and an overall risk rating for the company.

You can access this via 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": "/v0/legal-persons/lp.G6j5L7EjTB2KEpFKPCwrdQ",
            "overall-risk-rating": "low-risk",
            "overall-risk-score": {
                "risk-score-type": "number",
                "risk-score-value": 5
            },
            "risk-assessment-outcomes": [
                {
                    "legal-person-url": "/v0/legal-persons/lp.G6j5L7EjTB2KEpFKPCwrdQ",
                    "risk-factor-name": "Active directors",
                    "risk-rating": "low-risk",
                    "risk-score": {
                        "risk-score-type": "number",
                        "risk-score-value": 0
                    }
                },
                {
                    "legal-person-url": "/v0/legal-persons/lp.G6j5L7EjTB2KEpFKPCwrdQ",
                    "risk-factor-name": "Company sanctions",
                    "risk-rating": "low-risk",
                    "risk-score": {
                        "risk-score-type": "number",
                        "risk-score-value": 0
                    }
                },
                {
                    "legal-person-url": "/v0/legal-persons/lp.ZKiyGS80S1OkTAaOCjxmxg",
                    "risk-factor-name": "Individual tax residency",
                    "risk-rating": "low-risk",
                    "risk-score": {
                        "risk-score-type": "number",
                        "risk-score-value": 0
                    }
                }
              ...
            ]
        }
    ],
    "links": {
        "prev": null,
        "next": null
    }
}

Depending on the overall risk rating assigned, the application-status will change to accepted or declined (or referred if a manual review is required).

caution

Some checks 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.

5.1 Monitoring the application status​

You can poll the legal-person-url to monitor the application-status. You can also create a webhook and listen for the decision-created event.

curl 'https://api.griffin.com/v0/legal-persons/lp.Kfd8_BhpSdCqFKRYXa8d45' -H "Authorization: GriffinAPIKey$GRIFFIN_API_KEY"

The response will include the 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",  
            ...
    }

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