API Reference

The details of API endpoints for Web IDV.

get
Request Identity Verification

https://api.app.authenteq.com/web-idv/verification-url
This endpoint returns a URL that leads to Authenteq Identity Server. This endpoint is authorized with Basic Auth. You should use your Client ID and Client Secret from the Customer Dashboard as the credentials.
Request
Response
Request
Headers
Authorization
required
string
Your client credentials combined with a colon separator, base64-encoded and prefixed with "Basic ".
Query Parameters
redirectUrl
required
string
One of your registered redirect URLs that will be used to receive the code.
Response
200: OK
The verification session requested successfully. Your user should follow the verification URL to begin the identity process.
{
"verificationUrl": "https://web-idv.app.authenteq.com/verify?token=<token>"
}
400: Bad Request
The request contains an invalid data.
Missing Redirect URL
Redirect URL mismatch
No redirect URLs
Missing Redirect URL
{
"errorCode": "MISSING_REQUEST_PARAMETER",
"errorMessage": "Required 'redirectUrl' parameter is missing"
}
Redirect URL mismatch
{
"errorCode": "INVALID_REQUEST_PARAMETER",
"errorMessage": "Parameter 'redirectUrl' does not match any registered one"
}
No redirect URLs
{
"errorCode": "NO_REDIRECT_URLS",
"errorMessage": "No registered redirect URLs. Please specify at least one in Customer Dashboard"
}
401: Unauthorized
Full authentication is required to get a verification URL.
Missing API Keys
Invalid API Keys
Bad API Keys
Missing API Keys
{
"errorCode": "API_KEYS_MISSING",
"errorMessage": "No API Keys in the Authorization header"
}
Invalid API Keys
{
"errorCode": "API_KEYS_INVALID",
"errorMessage: "Invalid API Keys in the Authorization header"
}
Bad API Keys
{
"errorCode: "BAD_API_KEYS",
"errorMessage: "Bad API Keys"
}
403: Forbidden
Your account is deactivated and you can't start the identity process.
{
"errorCode": "ACCOUNT_DEACTIVATED",
"errorMessage": "Account deactivated. Please contact your Authenteq Sales Representative in order to keep using this service"
}

This endpoint should be called by your backend system.

The client secret, as its name suggests, is a secret and should never be made publicly available. It SHOULD NOT be stored in the frontend code that is run in the user's browser.

get
Get Verification Result Details

https://api.app.authenteq.com/web-idv/verification-result
The endpoint returns the verification result details extracted from the user document during identification. The verification result details are paired with the granted code. This endpoint is authorized with Basic Auth. You should use your Client ID and Client Secret from the Customer Dashboard as the credentials.
Request
Response
Request
Headers
Authorization
required
string
Your client credentials combined with a colon separator, base64-encoded and prefixed with "Basic ".
Query Parameters
redirectUrl
required
string
The redirect URL you used to request the verification session.
code
required
string
The code you got on redirect and granted to access the verification result details.
Response
200: OK
The details extracted from the user document.
{
"id": "3631324b-5bcc-48b0-b717-4f12f45e0a1d",
"status": "PASSED",
"platform": "WEB",
"startTime": "2020-04-10T11:44:40.644143+07:00",
"documentData": {
"documentType": "DL",
"documentNumber": "1234567890",
"issuingCountry": "USA",
"jurisdiction": "Uta",
"nationality": "USA",
"surnameAndGivenNames": "DOE JOHN",
"surname": "DOE",
"givenNames": "JOHN",
"nameSuffixes": "Mr",
"namePrefixes": "Jr",
"sex": "M",
"dateOfBirth": "1964-12-30",
"dateOfExpiry": "2022-12-30",
"dateOfIssue": "2012-05-30",
"licenseClass": "B/C/D",
"licenseClassDetails": {
"B": {
"from": "2019-01-30",
"to": "2029-01-30",
"notes": "Some valuable note"
},
"C": {
"from": "2019-01-30",
"to": "2029-01-30"
},
"D": {
"from": "2019-01-30",
"to": "2029-01-30"
}
},
"croppedFrontImage": {
"contentType": "image/jpeg",
"content": "Y3JvcHBlZEZyb250SW1hZ2U="
},
"croppedBackImage": {
"contentType": "image/jpeg",
"content": "Y3JvcHBlZEJhY2tJbWFnZQ=="
},
"faceImage": {
"contentType": "image/jpeg",
"content": "ZmFjZUltYWdlCg=="
}
}
}
400: Bad Request
The request contains an invalid data.
Missing code
Missing redirect URL
Invalid code
Redirect URL mismatch
Missing code
{
"errorCode": "MISSING_REQUEST_PARAMETER",
"errorMessage": "Required 'code' parameter is missing"
}
Missing redirect URL
{
"errorCode": "MISSING_REQUEST_PARAMETER",
"errorMessage": "Required 'redirectUrl' parameter is missing"
}
Invalid code
{
"errorCode": "INVALID_REQUEST_PARAMETER",
"errorMessage: "Parameter 'code' is invalid or expired"
}
Redirect URL mismatch
{
"errorCode": "INVALID_REQUEST_PARAMETER",
"errorMessage: "Parameter 'redirectUrl' does not match the given authorization code"
}
401: Unauthorized
Full authentication is required to get the verification result.
Missing API Keys
Invalid API Keys
Bad API Keys
Missing API Keys
{
"errorCode": "API_KEYS_MISSING",
"errorMessage": "No API Keys in the Authorization header"
}
Invalid API Keys
{
"errorCode": "API_KEYS_INVALID",
"errorMessage": "Invalid API Keys in the Authorization header"
}
Bad API Keys
{
"errorCode": "API_KEYS_BAD",
"errorMessage": "Bad API Keys"
}

This endpoint should be called by your backend system.

The client secret, as its name suggests, is a secret and should never be made publicly available. It SHOULD NOT be stored in the frontend code that is run in the user's browser.

The code can be used once only. On subsequent requests you will get an error that the code is invalid or expired.

The documentData field of the response can hold following properties:

Property

Description

Mandatory

Example

documentNumber

Number of ID document.

Yes

"FG617451", "8136431812"

issuingCountry

Three letter country code in ISO 3166-1 alpha-3 format of the country which issued the ID.

Yes

"DEU", "UKR", "USA"

documentType

Document type described by abbreviations:

  • PP - passport,

  • DL - driver's license,

  • NID - national ID.

Yes

"PP", "DL", "NID"

surnameAndGivenNames

String with surname and given names, separated by whitespace.

Yes

"GARCIA DILS ANNA MARIA DE O", "GOZHENKO VITALII"

surname

String with surname (family name), separated by whitespace.

No

"GARCIA DILS", "GOZHENKO"

givenNames

String with given names, separated by whitespace.

No

"ANNA MARIA DE O", "VITALII"

nameSuffixes

String with name suffixes, separated by whitespace.

No

"JR 3RD", "8TH"

namePrefixes

String with name prefixes, separated by whitespace.

No

"DR MRS", "DR"

nationality

Three letter country code in ISO 3166-1 alpha-3 format of the user’s nationality.

No

"DEU", "UKR", "USA"

dateOfBirth

Date of birth.

Yes

"1987-01-12"

dateOfExpiry

Date of document expiration.

No

"2017-01-30"

dateOfIssue

Date when document was issued.

No

"2017-01-30"

sex

Gender of the user. Can contain one of values:

  • F - female,

  • M - male,

  • X - unspecified.

No

"F", "M", "X"

licenseClass

The type of Driving License detected

No

"A","B","C"

jurisdiction

The state that issued the Identity document

No

"FL"

Not all documents contain surname and given names as separate fields. Quite often there is just a single field where surname and given names follow each other. So surname and givenNames fields exist in the retrieved document data only when they exist in the user document as separate ones.

Document images are returned in base64 format and will need to be decoded.