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"
}
}
]
}'
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.
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"
}
]
}'
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
- 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
}
]
}'
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.
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.
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 theverification-url
. - Outside of the request/response cycle, the verification may transition to
in-progress
and then to the final state ofchecks-complete
. - Once the verification reaches
checks-complete
, adecision
is created. - The verification may also transition to
failed
from either thepending
orin-progress
states if there is an error when communicating with our verification providers.
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.
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
.
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
.
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",
...
}