Skip to main content
Skip table of contents

GiroIdent Basis Flow

Introduction

GiroIdent Basis checks the user’s identity by comparing the user’s first and last name with the account holder name of the account the user will log on to.

Alternatively or additionally it is possible to provide a company name. In this case, individual results for the company name and/or user’s first and last name will be returned.

Moreover, a so-called “strict check” can be performed, in both the flag "strict-check" is set and an IBAN is provided. Only this IBAN will be considered for the account name validation, even if the user imports several of his bank accounts.

Prerequisites

TL:TR

Used Endpoints

In short, you need to call those 2 endpoints to perform an identity check.

Description

HTTP Method

Process Controller Endpoint

Link to API Doc

Create Basis check.

POST

/api/v2/checks

https://docs.finapi.io/?product=giroident#post-/checks

Get Basis check status and verdict.

GET

/api/v2/checks/{checkId}

https://docs.finapi.io/?product=giroident#get-/checks/-checkId-

Process Overview

The result of the identity check either can be obtained by registering a callback, or by polling the GET endpoint.

finAPI recommends to use a callback to receive the result.

Process With Callback

Process with Result Polling

cURL Example for Result Polling

Translated into cURL it looks like the following:

Step 1 - Create a Basic Identity Check

Create an identity check.

BASH
curl --location 'https://giroident2-sandbox.finapi.io/api/v2/checks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your OAUTH bearer token>' \
--data '{
    "first-name": "Finapi",
    "last-name": "Demobank",
    "company-name": "Big Deal AG",
    "iban": "DE77533700080111111100",
    "blz": "DEMO0001",
    "strict-check": false,
    "external-id": "12345"
}'

The result looks like this:

JSON
{
    "check-id": "3a824de8-1049-475c-89c4-71ad9716d379",
    "redirect-url": "https://webform-sandbox.finapi.io/wf/0cfb4a75-1b23-4e0e-9dee-12cf0739a55f"
}
Step 2 - Web Form

Open the redirect-url in a web browser.

Follow the instructions on the website. The test credentials to enter are user = Data Intelligence, password = Analysis.

Step 3 - Get the Result of the Basic Identity Check

Repeat the call to the “Query the GiroIdent Basis check result” endpoint with the check ID from Step 1, until the status is not “IN_PROGRESS" anymore.

BASH
curl --location 'https://giroident2-sandbox.finapi.io/api/v2/checks/3a824de8-1049-475c-89c4-71ad9716d379' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your OAUTH bearer token>' \
--data ''

The in-progress result looks like this:

JSON
{
    "status": "IN_PROGRESS"
}

The final result looks like this:

JSON
{
    "status": "COMPLETED",
    "name-equality": true,
    "name-equality-score": 1.0000
}

Identity Check Results

The recommendation for a check to be considered successful is to consider the result parameters and values

Parameter In Check Result

Value

status

COMPLETED

name-equality

true

Example Result: Successful Check

Parameter In Check Result

Value

status

COMPLETED

name-equality

true

name-equality-score

0.98

Example Result: Successful Check with Company Name

Parameter In Check Result

Value

status

COMPLETED

name-equality

true

name-equality-score

0.98

name-equality-details.person-name-equality

false

name-equality-details.person-name-equality-score

0.00

name-equality-details.company-name-equality

true

name-equality-details.company-name-equality-score

0.98

Example Result: Inconclusive Check - In Progress

Parameter In Check Result

Value

status

IN_PROGRESS

Example Result: Failed Check - Bank Login

Parameter In Check Result

Value

status

COMPLETED_WITH_ERROR

error-message

... BANK_REJECTION ... "

Example Result: Failed Check - Account Holder Name Validation

Parameter In Check Result

Value

status

COMPLETED

name-equality

false

name-equality-score

0.65

Example Result: Failed Check - Strict Check

Parameter In Check Result

Value

status

COMPLETED

status-details

[ "STRICT_CHECK_NO_IBAN_MATCH" ]

name-equality

false

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.