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.

Capture customer information
Choose your workflow
Run the verification
Complete the identity verification request
Inspect the risk assessment outcomes
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.

Limited company letting agents
Sole trader letting agents
Limited company landlords
Individual landlords

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.

1.3 Create a legal person to represent the company

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

1. Capture customer information

To run verification checks on a sole trader, you need to create an individual legal person to represent them and then add claims about them.

Full name
Date of birth
Nationality
Email address
Phone number
Tax residency
Residential address
Trading name
Industry and line of business
Business telephone number
Business email address
Business owner
Business website
Business address
Business start date
Does business trade under another name
Does business trade under another address
Description of the business
Annual turnover
Tax identification number (TIN) - optional if turnover is under £90k
If the business is VAT registered
List of non-UK countries where they operate (leave empty if not applicable)
Origins of deposits
Purpose(s) of the account
Source(s) of funds
Initial deposit
Cash payments
List of non-UK countries their accounts will receive payments from (leave empty if not applicable)
Properties under management
Landlords that are commercial or residential
HMO verification
HMRC registered
- HMRC registration number
CMP registration
- CMP scheme name / authority

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": "Floyd Black Landscaping",
    "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@fblandscaping.com"
        },
        {
            "claim-type": "individual-residence",
            "street-name": "Garden Avenue",
            "city": "Test Town",
            "postal-code": "TE1 2ST",
            "country-code": "GB",
            "building-number": "34"
        },
        {
            "claim-type": "mobile-number",
            "mobile-number": "+442012345678"
        },
        {
            "claim-type": "nationality",
            "country-code": "GB"
        },
        {
            "claim-type": "tax-residency",
            "tax-residency": "GB"
        },
        {
            "claim-type": "business-industry",
            "business-industry": "creative-industries",
            "line-of-business": "photography"
        },
        {
            "claim-type": "business-name",
            "business-name": "Floyd Black Photography"
        },
        {
            "claim-type": "business-address",
            "business-address": {
                "street-name": "Example Street",
                "city": "Test Town",
                "postal-code": "TE1 2ST",
                "country-code": "GB",
                "building-number": "16"
            }
        },
        {
            "claim-type": "business-owner",
            "business-owner?": true
        },
        {
            "claim-type": "business-telephone-number",
            "telephone-number": "+442087654321"
        },
        {
            "claim-type": "business-email-address",
            "telephone-number": "floyd@fbphotography.co.uk"
        },
        {
            "claim-type": "business-website",
            "telephone-number": "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 events and music concerts"
        },
        {
            "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",
            "purposes-of-account": [
                "long-term-investment"
            ]
        },
        {
            "claim-type": "individual-sources-of-funds",
            "sources-of-funds": [
                "savings"
            ]
        },
        {
            "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
        },
        {
            "claim-type": "managed-properties",
            "managed-property-count": 5
        },
        {
            "claim-type":"commercial-property-ratio",
            "commercial-property-percent":"commercial-0-percent"
        },
        {
            "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"
            }
        }
    ]
}'

info

In this example, you create the legal person and their claims in one go, but you can also create claims independently. See the API reference for more information about the different claims and their requirements.

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": {
    "street-name": "Argyle Street",
    "city": "London",
    "postal-code": "EC2V 9AN",
    "country-code": "GB"
  },
  "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"
    }
  ]
}'

1.3 Create a legal person to represent 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
Number of properties owned
What funds the landlord intends to receive into the account
HMRC registered
- HMRC registration number
HMO verification
Whether properties under management are residential, commercial, holiday lets or HMO
- If they own commercial properties, what industries

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": "property-types",
            "property-types": ["residential"]
        },
        {
            "claim-type": "commercial-property-industries",
            "property-industries": "not-applicable"
        },
        {
            "claim-type": "properties-origins-of-deposits",
            "properties-origins-of-deposits": [
                "tenant-rental-income"
            ]
        },
        {
            "claim-type": "hmo-license",
            "hmo-license?": true
        },
        {
            "claim-type": "hmrc-register",
            "hmrc-registration": {
                "hmrc-registration-type": "registered",
                "hmrc-registration-number": "123456"
            }
        }
    ]
}'

1. Capture customer information

To run verification checks on an individual, you need to create an individual legal person to represent them and then add claims about them. You will need their:

Full name
Date of birth
Nationality
Email address
Phone number
Tax residency
Residential address
Employment status
Industry and occupation
Income
Tax residency
Purpose(s) of the account
Source(s) of funds
Initial deposit
List of non-UK countries their accounts will receive payments from (leave empty if not applicable)
Number of properties owned
What funds the landlord intends to receive into the account
HMO verification
Whether properties under management are residential, commercial, holiday lets or HMO
- If they own commercial properties, what industries

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": "KLEIN, Monica",
    "legal-person-type": "individual",
    "claims": [
        {
            "claim-type": "individual-identity",
            "given-name": "Monica",
            "surname": "Klein",
            "date-of-birth": "1982-02-02"
        },
        {
            "claim-type": "contact-details",
            "email-address": "monicaklein@example.com"
        },
        {
            "claim-type": "individual-residence",
            "street-name": "Example Street",
            "city": "Test Town",
            "postal-code": "TE1 2ST",
            "country-code": "GB",
            "building-number": "19"
        },
        {
            "claim-type": "mobile-number",
            "mobile-number": "+442012345678"
        },
        {
            "claim-type": "employment",
            "employment-status": "employed",
            "occupation": "buyer",
            "industry-of-occupation": "sales"
        },
        {
            "claim-type": "individual-income",
            "income": {
                "value": "1000.00",
                "currency": "GBP"
            }
        },
        {
            "claim-type": "nationality",
            "country-code": "GB"
        },
        {
            "claim-type": "tax-residency",
            "tax-residency": "GB"
        },
        {
            "claim-type": "individual-purposes-of-account",
            "sources-of-funds": [
                "everyday-spending"
            ]
        },
        {
            "claim-type": "individual-sources-of-funds",
            "sources-of-funds": [
                "savings"
            ]
        },
        {
            "claim-type": "cash-payments",
            "cash-payments?": false
        },
        {
            "claim-type": "initial-deposit",
            "initial-deposit": {
                "currency": "GBP",
                "value": "1000.00"
            }
        },
        {
            "claim-type": "international-payments-countries",
            "international-payments-countries": [
                "GB"
            ]
        },
        {
            "claim-type": "managed-properties",
            "managed-property-count": 5
        },
        {
            "claim-type": "property-types",
            "property-types": [
                "residential"
            ]
        },
        {
            "claim-type": "commercial-property-industries",
            "property-industries": "not-applicable"
        },
        {
            "claim-type": "properties-origins-of-deposits",
            "properties-origins-of-deposits": [
                "tenant-rental-income"
            ]
        },
        {
            "claim-type": "hmo-license",
            "hmo-license?": true
        }
    ]
}'

info

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

1. Capture customer information​

1.1 Lookup Companies House record​

1.2 Capture company directors and PSCs​

1.3 Create a legal person to represent the company​

1. Capture customer information​

1. Capture customer information​

1.1 Lookup Companies House record​

1.2 Capture company directors and PSCs​

1.3 Create a legal person to represent the company​

1. Capture customer information​

2. Choose your workflow​

3. Run the verification​

Monitoring the verification​

4. Complete the identity verification request​

5. Inspect the risk assessment outcomes​

6. View the onboarding decision​

1. Capture customer information

1.1 Lookup Companies House record

1.2 Capture company directors and PSCs

1.3 Create a legal person to represent the company

1. Capture customer information

1. Capture customer information

1.1 Lookup Companies House record

1.2 Capture company directors and PSCs

1.3 Create a legal person to represent the company

1. Capture customer information

2. Choose your workflow

3. Run the verification

Monitoring the verification

4. Complete the identity verification request

5. Inspect the risk assessment outcomes

6. View the onboarding decision