Handle declines

When a verification is declined, the decision carries a decline-reasons array explaining why. This page covers what those reasons contain and how to handle them.

Decline reasons are available wherever a decision appears:

• GET /v0/legal-persons/{legal-person-id}/decisions
• GET /v0/legal-persons/{legal-person-id} on latest-decision
• GET /v0/legal-persons/{legal-person-id}/history
• GET /v0/onboarding/applications/{onboarding-application-id}
• the decision-created webhook event

The shape

{
  "decision-outcome": "declined",
  "decision-notes": "",
  "decline-reasons": [
    {
      "decline-reason-code": "failed-idv-no-bureau-match",
      "decline-reason-title": "Failed ID&V - No bureau match",
      "decline-reason-description": "The applicant's identity could not be matched against the records we check. Check the applicant's name, date of birth and address, correct any errors and resubmit.",
      "legal-person-url": "/v0/legal-persons/lp.7Flg81UuVY-4RT3zXY7YXA"
    },
    {
      "decline-reason-code": "failed-idv-no-bureau-match",
      "decline-reason-title": "Failed ID&V - No bureau match",
      "decline-reason-description": "The applicant's identity could not be matched against the records we check. Check the applicant's name, date of birth and address, correct any errors and resubmit.",
      "legal-person-url": "/v0/legal-persons/lp.zcpzOqLGUeute0aAKUvUEQ"
    },
    {
      "decline-reason-code": "incorrect-information",
      "decline-reason-title": "Incorrect information",
      "decline-reason-description": "Information submitted with this application was incorrect. Check the application details, correct them and resubmit.",
      "legal-person-url": "/v0/legal-persons/lp.1VNk_zpdVzqcOp85NLY_gg",
      "decline-reason-claim-types": ["individual-identity"]
    },
    {
      "decline-reason-code": "outside-risk-appetite",
      "decline-reason-title": "Outside our risk appetite",
      "decline-reason-description": "This application does not meet Griffin's risk appetite. Resubmitting will not change the outcome."
    }
  ]
}

Field	Description
decline-reason-code	Unique, stable code that identifies the reason.
decline-reason-title	Human-readable summary, suitable for display.
decline-reason-description	Further detail, and what to do next.
legal-person-url	The profile the reason applies to. Present on every reason except outside-risk-appetite.
decline-reason-claim-types	Which claims the reason applies to. Present on incorrect-information only.

The full list of codes is in the API reference.

You can download every code that can be returned, with its title and description, as a CSV.

Which profile a reason applies to

An application can cover more than one profile, a company and its directors, for example. A decline reason usually belongs to one of them. The legal person it applies to is given by legal-person-url.

This matters because the same code can appear more than once. In the example above, two directors each failed the same identity check, so there are two failed-idv-no-bureau-match entries that are identical except for legal-person-url.

Outside of risk appetite

In cases when the onboarded customer is outside of Griffin's risk appetite, the following reason is returned:

Code	Title	Legal person URL
outside-risk-appetite	Outside our risk appetite	N/A

This is all the detail we can provide and no further explanation would be given on request.

What to do next

As well as explaining the decline, decline-reason-description clarifies if anything can be done about it. There are these options:

• Correct the data and resubmit: something you submitted may be wrong and you can fix it. The decline reasons explain what needs to be corrected before submitting a new verification.
• Resubmit once external data changes: what you submitted was correct, but some external data (e.g. information about a company in the Companies House register) may need to be updated before submitting a new verification.
• Nothing to retry: resubmitting will not change the outcome.
• Contact Griffin: the issue is on our side and you need to contact Griffin support before resubmitting.

caution

The wording of the description is subject to change. Don't rely on it to programmatically determine the course of action. Use decline-reason-code instead.

Handling the array

Reasons of different kinds can appear in the same decision, as in the example above. Three things to keep in mind:

• Order carries no meaning. Reasons are sorted by title, then by legal-person-url. No one reason is the primary cause.
• Handle unknown codes gracefully. New codes may be added over time.