Retrieving identification results in JSON format

The usual next step after an OnFinal webhook and the getStatus request is the getIdentData request with the subsequent logic.

If required, your account can be configured to return the data encrypted.

Requirements

The order must be finally processed. For a list of final status see the List of Status Codes.

Method and URL

[GET] https://customer.identity.tm/api/2.10/getIdentData/[OrderID]
[GET] https://customer.identity.tm/api/2.10/getIdentData/[OrderID]/IncludeInitialData
[GET] https://customer.identity.tm/api/2.10/getIdentData/[OrderID]/IncludeIdentifyMethod
[GET] https://customer.identity.tm/api/2.10/getIdentData/[OrderID]/IncludeIdentifier
[GET] https://customer.identity.tm/api/2.10/getIdentData/[OrderID]/Signed
[GET] https://customer.identity.tm/api/2.10/getIdentData/[OrderID]/crypt
[GET] https://customer.identity.tm/api/2.10/getIdentData/[OrderID]?fullDocumentsList=true

Variants

Variant	Description
Default	Normal variant, response as described below
IncludeInitialData	Include initial data as given to the putOrder request
IncludeIdentifyMethod	Include an additional element in the response "IdentifyMethod"
IncludeIdentifier	Include the internal user ID of the identifier
Signed	Return signed and encrypted version of the identification data for later re-use
crypt	Encrypt response content using AES-256/GCM/NoPadding and a 23 byte long IV prefixed to the encrypted content. This variant can be used in combination with the other variants.
IncludeEidJwt	Include transaction attestation for the identitfication by eID (JWT)
fullDocumentsList	Query parameter (?fullDocumentsList=true). When set, the IDCard element is replaced by a Documents array containing all documents scanned during the Reader process.

Response Data

Note: To include the images in the response, your account needs to be configured accordingly. Contact IDnow to change your configuration. This setting has an impact on the data format -- if images are included, the element IdentData will be an object otherwise an array.

Element	Parent	Type	Len	Occ	Description
Identitfied	[ROOT]	DTS		Y	Time of identification The typo in the name is kept for backward compatibility
IdentifyMethod	[ROOT]	S		Dep	Method of identification used for this order; one of: Shop, Video, eID, Giro, AutoID, SmartID. Only if specifically requested
Identifier	[ROOT]	S/N		Dep	Internal user ID of user who conducted the identification Only if specifically requested
UserIp	[ROOT]	S		Dep	IP address of user while conducting the identification. Will only be collected and returned, if configured on your account.
OcrStatus	[ROOT]	N		Dep	In case of POS ident orders, this field tells about OCR processing status: 0 no OCR processed 1 OCR and manual images processed 2 only OCR processed
eIdUsed	[ROOT]	B		Dep	In case of POS ident orders, this field tells if eID has been conducted or not
SecurityCheckFailed	[ROOT]	B		Dep	In case of POS ident orders, this field is true in case the on-device security check failed
FraudAttempt	[ROOT]	B		Dep	True indicates a potential fraud attempt. Only if fraud attempt has been flagged by an agent.
eidJwt	[ROOT]	S		Dep	Transaction attestation for the identitfication by eID (JWT) Only if specifically requested
IdentData	IdentData	O/A		Y	Type (object or array) depends on whether images are included in response or not
Type	IdentData	N		Dep	1 Checked data 2 Initial data from putOrder
Firstname	IdentData	S	50	Y
Surname	IdentData	S	50	Y
Street	IdentData	S	100	Y
ZipCode	IdentData	S	5	Y
City	IdentData	S	100	Y
Country	IdentData	S		Dep	Only if noted on identity document
Birthdate	IdentData	DS		Y
Birthplace	IdentData	S	100	Y
Birthname	IdentData	S	75	Dep	Only if requested
Nationality	IdentData	S	50	Dep	Only if noted on identity document
Title	IdentData	S	50	Dep	Only if noted on identity document
Artistname	IdentData	S	50	Dep	Only if noted on identity document
Gender	IdentData	S		Dep	female/male/diverse
Mobile	IdentData	S	50	Dep	Only if verified with TAN
Email	IdentData	S	100	Dep	Only if verified with TAN
IDCard	IdentData	O		Dep	In case of a license check without ID, this field will not be included
CardNo	IDCard	S	50	Dep	In case of an eID-only identification, will field will not be included
eidRestrictedIdentifier	IDCard	S		Dep	Restricted Identifier (dienste- und kartenspezifisches Kennzeichen - DKK); only if eID was used to identity user
extDocumentType	IDCard	N		Dep	Specifies the document(s) used. If multiple documents have been used, the individual values will be or'ed bitwisely. 0 Custom document 1 ID Card 2 Passport 4 Residence permit 8 Driver's license 16 German eID-Card for EU citizens All other values are reserved for future use. New values may be added at any time.
PlaceOfIssue	IDCard	S	100	Dep	In case of an eID-only identification, will field will not be included
CountryOfIssue	IDCard	S	3	Dep	Depends on customer specific requirements and document
DateOfIssue	IDCard	DS		Dep	In case of an eID-only identification, will field will not be included
ValidUntil	IDCard	DS		Dep	Depends on customer specific requirements
Type	IDCard	S		Dep	IDCard/Passport or LegitimationDocument provided in putOrder
Documents	IdentData	A		Dep	Array of all documents scanned during the Reader process. Present only when query parameter fullDocumentsList=true is passed. Replaces the IDCard element.
Type	Documents	S		Dep	Document type. One of: IdCard, Passport, ResidencePermit, ResidencePermitSticker, DriversLicense, EidCard, Visa, CrewMemberCertificate
Firstname	Documents	S	50	Dep
Surname	Documents	S	50	Y
Street	Documents	S	100	Dep
ZipCode	Documents	S	5	Dep
City	Documents	S	100	Dep
Birthdate	Documents	DS		Y
Birthplace	Documents	S	100	Dep
Nationality	Documents	S	3	Y	ISO 3166-1 alpha-3
Gender	Documents	S		Dep	female/male/diverse
CardNo	Documents	S	50	Y
IssuingStateOrOrganization	Documents	S	3	Y	ISO 3166-1 alpha-3
PlaceOfIssue	Documents	S	100	Dep
DateOfIssue	Documents	DS		Dep
ValidUntil	Documents	DS		Dep
TypeOfPermit	Documents	S		Dep	Type of residence permit. Only present for residence permit documents (ResidencePermit, ResidencePermitSticker).
RemarksOfPermit	Documents	S		Dep	Remarks on the residence permit. Only present for residence permit documents (ResidencePermit, ResidencePermitSticker).
Sources	Documents	O		Dep	Machine-readable source data extracted from the document
Mrz	Sources	O		Dep	Parsed MRZ (Machine Readable Zone) data. Present only when an MRZ was successfully read and parsed.
Raw	Mrz	S		Y	Raw MRZ string
DocumentCode	Mrz	S		Y
IssuingStateOrOrganization	Mrz	S	3	Y	ISO 3166-1 alpha-3
Surname	Mrz	S		Y
Firstname	Mrz	S		Dep
CardNo	Mrz	S		Y
Nationality	Mrz	S	3	Y	ISO 3166-1 alpha-3
Birthdate	Mrz	S		Y
Gender	Mrz	S		Y	female/male/diverse
ValidUntil	Mrz	S		Y
CheckDigits	Mrz	O		Dep	Check digit validation results. Contains one entry each for CardNo, Birthdate, ValidUntil, and Overall (all optional). Each entry has Extracted (S), Calculated (S), and IsValid (B).
DriverLicence	IdentData	O		Dep	If enabled in putOrder
LicenceNo	DriverLicence	S	50	Dep	If enabled in putOrder
Classes	DriverLicence	S	50	Dep
DateOfIssue	DriverLicence	DS		Dep
Additional	IdentData			Dep	If set in putOrder
<detail>	Additional	S	150	N	If set in putOrder
Images	IdentData	A		Dep	If enabled on your account
Image	Images	S			Base64 encoded Data
Filename	Images	S	100		Filename for the data

HTTP Codes

200 OK, JSON document in response body

400 Bad request, error description in body

401 Authentication failed, please check username and password

404 Order not found

Example Request

[GET] https://customer.identity.tm/api/2.10/getIdentData/99921269855041/IncludeInitialData

Example Response

{
  "Identitfied": "2018-09-05T11:06:21+02:00",
  "IdentData": [
    {
      "Type": 1,
      "Firstname": "Erika",
      "Surname": "Mustermann",
      "Street": "Heidestr. 17",
      "ZipCode": "43000",
      "City": "Köln",
      "Birthdate": "1964-08-12",
      "Birthplace": "Berlin",
      "Nationality": "DE",
      "Gender": "female",
      "Mobile": "+4915114084205",
      "IDCard": {
        "CardNo": "T22000129",
        "PlaceOfIssue": "Stadt Köln",
        "ValidUntil": "2020-10-31",
        "Type": "IDCard"
      }
    },
    {
      "Type": 2,
      "Firstname": "Erika",
      "Surname": "Mustermann",
      "Street": "Heidestr. 17",
      "ZipCode": "43000",
      "City": "Köln",
      "Birthdate": "1964-08-12",
      "Birthplace": "Berlin",
      "Nationality": "DE",
      "IDCard": {
        "CardNo": null,
        "PlaceOfIssue": null,
        "ValidUntil": "1970-01-01"
      }
    }
  ]
}