GiroIdent Plus Flow

Introduction

GiroIdent Plus 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. Additionally. the user’s data is validated using the SCHUFA Identity Check web service.

GiroIdent Basis Flow

Prerequisites

The major prerequisite is to have a valid set of client credentials: client_id and client_secret.
A user has already been created
- With self-managed user: Getting Started - User Management
- With Process Controller: Obtain Authorization via Process Controller (recommended)
An OAuth bearer token has been obtained.

TL:TR

Used Endpoints

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

Description	HTTP Method	Process Controller Endpoint	Link to API Doc
Create Plus check.	POST	`/api/v2/checks-plus`	finAPI API Documentation
Get Plus check status and verdict.	GET	`/api/v2/checks-plus/{checkId}`	finAPI API Documentation

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.

CODE

curl --location 'https://giroident2-sandbox.finapi.io/api/v2/checks-plus' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your OAUTH bearer token>' \
--data '{
    "first-name": "Finapi",
    "last-name": "Demobank",
    "iban": "DE77533700080111111100",
    "blz": "DEMO0001",
    "strict-check": false,    
    "gender": "M",
    "date-of-birth": "1980-01-01",
    "current-address": {
        "street": "Adams-Lehmann-Str. 44",
        "zip": "80797",
        "city": "München",
        "country": "DEU"
    },
    "schufa-user-id": "<your SCHUFA ID for Identity Check>",
    "schufa-password": "<your SCHUFA password>",
    "external-id": "12345"
}'

The result looks like this:

CODE

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

GiroIdent Basis Flow

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 Plus Identity Check

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

CODE

curl --location 'https://giroident2-sandbox.finapi.io/api/v2/checks-plus/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:

CODE

{
    "status": "IN_PROGRESS"
}

The final result looks like this:

CODE

{
    "status": "COMPLETED",
    "name-equality": true,
    "name-equality-score": 1.0000,
    "schufa-identity-check": 100.0000,
    "schufa-identity-check-details": {
        "birthday-match-score": 100.0000,
        "city-match-score": 100.0000,
        "street-match-score": 100.0000,
        "zip-match-score": 100.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`
schufa-identity-check	not, respectively greater than`0.0000`

Example Result: Successful Check

Parameter In Check Result	Value
status	`COMPLETED`
name-equality	`true`
name-equality-score	`0.98`
schufa-identity-check	`95.0000`
schufa-identity-check-details.birthday-match-score	`100.0000`
schufa-identity-check-details.city-match-score	`100.0000`
schufa-identity-check-details.street-match-score	`90.0000`
schufa-identity-check-details.zip-match-score	`100.0000`

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`
schufa-identity-check	`100.0000`
schufa-identity-check-details.birthday-match-score	`100.0000`
schufa-identity-check-details.city-match-score	`100.0000`
schufa-identity-check-details.street-match-score	`100.0000`
schufa-identity-check-details.zip-match-score	`100.0000`

Example Result: Failed Check - Identity Validation

Parameter In Check Result	Value
status	`COMPLETED`
name-equality	`true`
name-equality-score	`0.99`
schufa-identity-check	`0.0000`
schufa-identity-check-details.birthday-match-score	`0.0000`
schufa-identity-check-details.city-match-score	`100.0000`
schufa-identity-check-details.street-match-score	`100.0000`
schufa-identity-check-details.zip-match-score	`100.0000`