Sample structures of the E_KYC_CHECK API responses for German eID Verification (deu_gov_eid).

GREEN

The following response example represents successful checks.

{
  "checks": [
    {
      "answer": "GREEN",
      "checkType": "E_KYC_CHECK",
      "createdAt": "2025-04-01 15:32:05",
      "id": "ebb45e98-f01a-4322-9367-ce5979c0a1fe",
      "inputDoc": {
        "idDocType": "OTHER3",
        "country": "DEU"
      },
      "extractedDoc": {
        "country": "DEU",
        "idDocType": "ID_CARD", // ID_CARD or RESIDENCE_PERMIT
        "firstName": "HANS-GÜNTHER",
        "lastName": "VON DREBENBUSCH-DALGOẞEN",
        "dob": "1984-01-26",
        "addresses": [
          {
            "street": "WEG NR. 12 8E",
            "town": "HAMBURG",
            "postCode": "22043",
            "country": "DEU"
          }
        ],
        "placeOfBirth": "BREMERHAVEN",
        "nationality": "DEU",
        "validUntil": "2034-01-25",
        "additionalFields": [
          {
            "name": "birthName",
            "value": "WEIẞ"
          },
          {
            "name": "documentType",
            "value": "ID"
          },
          {
            "name": "restrictedId",
            "value": "OTLIjJ8wwn0IKAzHYGvK/pCp/UVHRDZoCSYmMjz/DVY="
          }
        ]
      },
      "ekycCheckInfo": {
        "confirmationId": "u4TxVYKHumSNySswwkY0tXqa",
        "confirmationType": "eID"
      }
    }
  ]
}

YELLOW

The following example illustrates a case where the verification process is still in progress and the applicant has not yet completed all required steps.

{
  "checks": [
    {
      "answer": "YELLOW",
      "checkType": "E_KYC_CHECK",
      "createdAt": "2026-05-06 13:05:54",
      "id": "51f19e5d-73e8-43a2-8fcd-77b8dad4c59e",
      "inputDoc": {
        "idDocType": "OTHER3",
        "country": "DEU"
      },
      "databasePersonCheckInfo": {
        "processingEvents": [
          {
            "event": "eidCardLost",
            "date": "2026-05-06 13:06:22"
          },
          {
            "event": "eidWrongPinFirstAttempt",
            "date": "2026-05-06 13:06:51"
          }
        ]
      },
      "ekycCheckInfo": {
        "confirmationId": "wWe9uIJKYcpGwoIR6CyvcijY",
        "confirmationType": "eID"
      }
    }
  ]
}

Response explained

The response represents a list of checks.

📘
Note
For the complete common response structure, see the parent page. The sections below describe German eID Verification (deu_gov_eid) specific details.

`additionalFields` element fields

An array of key-value pairs providing non-standard additional information. The following table explains the possible keys.

Field	Type	Description
`birthName`	String	Birth name (Geburtsname).
`documentType`	String	Provided identity document type: `ID` — German Identity Card (Personalausweis). `AR`, `AS`, `AF` — Residence permit (Elektronischer Aufenthaltstitel). `UB` — eID Card for EU/EEA citizens (Unionsbürgerkarte)
`restrictedId`	String	Service- and card-specific ID.

ℹ️ Value of extractedDoc.idDocType is determined by documentType:

documentType	extractedDoc.idDocType
`ID` or `UB`	`ID_CARD`
`AR`, `AS`, or `AF`	`RESIDENCE_PERMIT`

`databasePersonCheckInfo` attributes

The databasePersonCheckInfo object includes verification results and metadata for database verification.

Field	Type	Description
`processingEvents`	Array of objects	Timeline of events captured throughout the verification lifecycle. ⚠️ Currently available only for German eID Verification when using MSDK version 1.42 or later.

`processingEvents` attributes

The processingEvents object represents an individual audit entry within the verification lifecycle.

Field	Type	Description
`event`	String	Type of event or status code being recorded (for example, `eidGeneralError` or `eidCardLocked`). The same event type may appear multiple times in the timeline.
`date`	Date	Date and time of the event in UTC.

Possible `event` values

The following values may appear in the event field, representing specific milestones or errors during the eID verification process.

Event	Description
`eidGeneralError`	Error when unblocking the card.
`eidHTTPError`	Unexpected backend response error.
`eidInvalidToken`	Mobile token is invalid.
`eidTokenExpired`	Mobile token has expired.
`eidInvalidProcessRequirements`	Process configuration is not supported by the client/backend combination.
`eidIncompatibleClientVersion`	eID library or SDK version is outdated and requires an update.
`eidNFCNotAvailable`	NFC is disabled or not physically available on the device.
`eidCardLocked`	ID card is blocked after too many incorrect PIN attempts and requires a PUK to unblock.
`eidCardDeactivated`	The eID function on the ID card is disabled and must be activated by the authorities.
`eidCardLost`	NFC connection was interrupted because the card was moved away during the reading process.
`eidInvalid` / `eidCardInvalid`	The user's card is blocked remotely, expired, or otherwise invalid and cannot be used.
`eidNoCard`	A non-compatible NFC tag was detected instead of a valid eID card.
`eidSessionExpired`	The five-minute eID session timeout occurred.
`eidAuthenticationFailed`	eID communication failure, usually caused by an environment mismatch (for example, a test card used in production or vice versa).
`eidCertificatePinningFailed` / `eidCertificateValidationFailed`	Security failure caused by a certificate hash mismatch.
`eidWrongPin`	Incorrect PIN entered.
`eidWrongPinFirstAttempt`	Incorrect PIN entered; two attempts remaining.
`eidWrongPinLastAttempt`	Incorrect PIN entered; one attempt remaining before the card is locked.
`eidWrongCan`	Incorrect Card Access Number (CAN) entered.
`eidWrongPuk`	Incorrect Personal Unblocking Key (PUK) entered.
`eidWrongTransportPinFirstAttempt`	Incorrect Transport PIN entered; two attempts remaining.
`eidWrongTransportPinLastAttempt`	Incorrect Transport PIN entered; one attempt remaining before lock.
`eidNewPinMismatch`	New PIN and confirmation PIN do not match.
`eidIncompatibleDevice`	Device hardware does not support the required NFC Extended Length format.
`eidNetworkError`	No internet connection.
`eidUnknownError`	An unhandled or unexpected error occurred.

GREEN

YELLOW

Response explained

Note

additionalFields element fields

databasePersonCheckInfo attributes

processingEvents attributes

Possible event values

`additionalFields` element fields

`databasePersonCheckInfo` attributes

`processingEvents` attributes

Possible `event` values