Skip to main content

Onboard letting agents and landlords with Verify

This guide will show you how to onboard your customers that are in the property sector using Verify. Verify is our onboarding product for running automated KYC/KYB checks on your customers.

This guide assumes you know your $GRIFFIN_API_KEY and $ORGANIZATION_ID already. If you don't, go get started with the API.

There are six steps to onboarding your customers that are letting agents or landlords.

  1. Capture customer information
  2. Choose your workflow
  3. Run the verification
  4. Complete the identity verification request
  5. Inspect the risk assessment outcomes
  6. View the onboarding decision

The first step will be different depending on what type of customer you want to onboard. Currently, we support onboarding for UK limited companies and sole trader letting agents. We also support onboarding for UK limited companies and individual landlords. To see the requirements needed if you are using our Reliance workflows take a look at our Reliance onboarding guide.

1. Capture customer information​

1.1 Lookup Companies House record​

Find the information for the UK company you wish to onboard by querying Companies House with their unique 8-digit company number.

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 any other people with significant control (PSCs). PSCs are sometimes called beneficial owners.

{
  "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 Capture company directors and PSCs​

The company, its directors, and its PSCs are all represented as legal persons in the API. The company is a corporation legal person. Directors and PSCs are individual legal persons.

To create an individual legal person to represent a director or PSC, 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 have a 201 status code. The URL addressing the newly created legal person (e.g. /v0/legal-persons/lp.njk7tIWvQJGPEFIdDmS9yQ) will be present at both the response's Location header and the legal-person-url in the response body. Save this URL so you can associate it with the company in the next step.

Create a corporation legal person representing the company, and use the information collected in step 1.1 to create a uk-company-register claim. Use director and person with significant control claims to associate the 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 where 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
  • Properties under management
  • Landlords that are commercial or residential
  • Origins of deposits
  • HMO verification
  • HMRC registered
    • HMRC registration number
  • CMP registration
    • CMP scheme name / authority
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
        },
        {
            "claim-type": "managed-properties",
            "managed-property-count": 5
        },
        {
            "claim-type":"commercial-property-ratio",
            "commercial-property-percent":"commercial-0-percent"
        },
        {
            "claim-type": "properties-origins-of-deposits",
            "properties-origins-of-deposits": [
                "tenant-rental-income"
            ]
        },
        {
            "claim-type": "hmo-verification",
            "hmo-verification": "yes"
        },
        {
            "claim-type": "hmrc-register",
            "hmrc-registration": {
                "hmrc-registration-type": "registered",
                "hmrc-registration-number": "123456"
            }
        },
        {
            "claim-type": "client-money-protection-scheme",
            "client-money-protection-scheme": {
                "scheme-registration-type": "registered",
                "scheme-details": "Scheme name"
            }
        }
    ]
}'

2. Choose your workflow​

Once you've created a legal-person representing your customer, you need choose your workflow - this determines the specific set of verification checks to be run on the customer. If your organisation already has predefined workflows, you can see them by querying organization-workflows-url, as shown below.

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

In sandbox mode, you can choose from a standard set of sample workflows. If you are onboarding a letting agent then you will need to use either the LTD Company Property workflow or the Sole Trader Property workflow. If you are onboarding a landlord you will need to use either the LTD Company Landlord workflow or the Individual Landlord workflow.

{
  "workflows": [
    {
      "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "LTD Company Property",
      "legal-person-type": "corporation"
    },
    {
      "workflow-url": "/v0/workflows/wf.W1NwgL6sXCmB3u9cPiJoKQ",
      "display-name": "Sole Trader Property",
      "legal-person-type": "individual"
    },
    {
      "workflow-url": "/v0/workflows/wf.G3yYmojQV32I814_5JLTEQ",
      "display-name": "Individual Landlord",
      "legal-person-type": "individual"
    },
    {
      "workflow-url": "/v0/workflows/wf.Ul-1r4gRWfOFxHJsHWghcA",
      "display-name": "LTD Company Landlord",
      "legal-person-type": "corporation"
    }
  ]
}

Save the relevant workflow-url to use in the next step.

3. Run the verification​

Now you can submit the legal person representing your customer for verification. Verification is a series of checks you run on a legal person to a) make sure they are who they say they are and b) figure out what level of financial crime risk they pose.

The verification process is asynchronous and runs as follows.

  • The verification starts in a pending state and a response is served immediately, including the verification-url.
  • Outside of the request/response cycle, the verification may transition to in-progress and then to the final state of checks-complete.
  • Once the verification reaches checks-complete, a decision is created.
  • The verification may also transition to failed from either the pending or in-progress states if there is an error when communicating with our verification providers.
info

The example verification below is created against an individual legal person, but the process is the same for a corporation legal person.

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

The response will look like this. You can use the verification-url for monitoring or register a webhook and listen for the events.

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

Monitoring the verification​

To monitor the verification you can poll the verification-url or register 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 processing is finished when the verification-status reaches checks-complete, as shown in the example.

{
  "created-at": "2022-08-15T10:47:51.959Z",
  "display-name": "FLORES, Julia",
  "legal-person-type": "individual",
  "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"
}

4. Complete the identity verification request​

To enable your customers to complete our identity and verification (ID&V) checks, they are required to submit a selfie and photo of their ID. To manage this request you can get the ID&V link from idv-check-url within /verifications/<:verification-id>/resources which will need to be shared with your customer.

info

If you are onboarding a company, the identified directors and PSCs will need to complete ID&V.

The response will look like this: 

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

To get notified of when the link is available you can poll the verification URL.

info

No selfies or ID photos are captured in sandbox mode and all ID&V results are mock-ups. Learn more about sandbox vs. live mode.

5. Inspect the risk assessment outcomes​

Once the verification reaches checks-complete, we run a detailed risk assessment and produce an overall risk rating.

You can access these by navigating to the verification-risk-assessments-url.

info

Some checks in a workflow 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.

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

6. View the onboarding decision​

Once we have the risk assessment outcomes, the application-status will change to accepted or declined depending on the overall risk rating (or referred if a manual review is required).

You can poll the legal-person-url to monitor the application-status for the customer or you can register a weekhook 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 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": "2022-08-15T10:47:51.959Z"
    },
  "display-name": "FLORES, Julia",
  "application-status": "accepted",
  "status-changed-at": "2019-08-24T14:15:22Z",
  "created-at": "2019-08-24T14:15:22Z",
  ...
}