Base URL: https://demo-api.incodesmile.com — Incode demo environment
This endpoint is used for storing front side of id for further processing. Image quality check is performed during that call. Number of retries is not limited.
Once process-id is finished, this endpoint cannot be called for retries.
Note: Front side of id should be uploaded before back-side
Path & query parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
onlyFront |
query | boolean | Flag stating if document is one-sided (like Passport) | |
extractIdFace |
query | boolean | When false, skips biometric face extraction and template creation from the front ID. Default true. | |
api-version |
header | string | yes |
Request body
Front side of id. In case of passport, this should be page with all data about user.
Content-Type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
base64Image |
string | Image in base64 format. One of base64Image or imageUrl is required | |
imageUrl |
string | URL of the image. One of base64Image or imageUrl is required |
Responses
200
In case there's some issue when calling the endpoint due to classification failed, an issue such as bad quality, or any of the fail reasons the response will always have the field:
- classification
- failReason
- sharpness
- glare
- horizontalResolution
We recommend considering the call as failed if there's a failReason in the response or if the classification is false. Possible values for fail reason:
- UNKNOWN_DOCUMENT_TYPE: document classification failed
- WRONG_DOCUMENT_SIDE: can happen when uploading back side of id when front id is required or the other way around
- WRONG_ONE_SIDED_DOCUMENT: uploading wrong document with only one side
- WRONG_UNFOLDED_DOCUMENT: uploading unfolded document with unrecognizable sides
- UNFOLDED_DOCUMENT_PAGE_MISMATCH: uploading unfolded document with mismatching sides
- DOCUMENT_NOT_READABLE: document couldn't be read, probably due to image quality
- UNABLE_TO_ALIGN_DOCUMENT: alignment failed
- ID_TYPE_UNACCEPTABLE: invalid type of id
- UNEXPECTED_ERROR_OCCURRED: unexpected error
Whenever the classification is done successfully the fields that will always be present are:
- classification
- sharpness
- glare
- horizontalResolution
- readability
- typeOfId
- sessionStatus
The remaining fields could be optional depending on the specific type of id and country of origin.
Response body (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
correctSharpness |
boolean | It's true if the sharpness of the ID meets the requirements. | |
correctGlare |
boolean | It's true if the glare of the ID meets the requirements. | |
horizontalResolution |
integer (int32) | Value is based on the resolution of the cropped photo. Low value means after performing the crop we have a bad quality of image. We recommend to retry capture if value is below 155. | |
shadowConfidence |
number (float) | Value 0 means it is no shadow on the image and image quality is good, while value 1 represents bad quality of image with a lot of shadow. We recommend to retry capture if value is 1. | |
classification |
boolean | If true, server classified image as a front side of an id. If false, server failed to classify image as valid front side of an id or passport and other parameters can be ignored. | |
readability |
boolean | If true, server can properly read ID. If false server failed to read some key places of the ID. | |
typeOfId |
string | Enum: Unknown, Passport, Visa, DriversLicense, IdentificationCard, Permit, Currency, ResidenceDocument, TravelDocument, BirthCertificate, VehicleRegistration, Other, WeaponLicense, TribalIdentification, VoterIdentification, Military, TaxIdentification, FederalID, MedicalCard |
|
issueYear |
integer (int32) | Issue year of the ID. | |
issueName |
string | Description of the ID. Could contain country code, state, type of ID, subtype of ID. | |
curpCheck |
boolean | Only for Mexican IDs. Flag stating if curp was properly read. | |
sessionStatus |
string | Session Status Enum: Alive, Closed, Deleted |
|
countryCode |
string | Valid ISO alpha-2 or alpha-3 code of the ID issuing country. | |
state |
string | Issuing state of the ID. | |
failReason |
string | Classification fail reason Enum: UNKNOWN_DOCUMENT_TYPE, WRONG_DOCUMENT_SIDE, WRONG_ONE_SIDED_DOCUMENT, UNFOLDED_DOCUMENT_PAGE_MISMATCH, WRONG_UNFOLDED_DOCUMENT, DOCUMENT_NOT_READABLE, UNABLE_TO_ALIGN_DOCUMENT, ID_TYPE_UNACCEPTABLE, UNEXPECTED_ERROR_OCCURRED, DIGITAL_ID_REQUESTED_BUT_OTHER_PROVIDED |
|
skipBackIdCapture |
boolean | Flag that signals if back id capture should be skipped or not. | |
forceFrontIdCapture |
boolean | Flag that signals if front id capture must be executed after back. | |
showMandatoryConsent |
boolean | Render mandatory consent page based on this parameter value. | |
regulationType |
string | Regulation type for the mandatory consent (only if showMandatoryConsent set to true). | |
skipGlareFront |
boolean | Flag that signals if front side glare should be ignored. | |
skipGlareBack |
boolean | Flag that signals if back side glare should be ignored. | |
documentIsOnTheEdge |
boolean | Flag that signals if document is on the edge on the full frame image. | |
acceptedDocuments |
array[string] | List of accepted documents for that particular country in case of ID_TYPE_UNACCEPTABLE failReason. | |
imageRedacted |
boolean | Flag that signals if image was redacted as part of the ID capture. | |
idFaceExtractionSkipped |
boolean | True when biometric face extraction from the front ID was skipped because the client passed extractIdFace=false. While this flag is true, face-match flows that require an ID-side template cannot run; the flag is cleared on a subsequent add/front-id call where extractIdFace is true (or omitted). | |
captureAttemptsLimit |
object | Checked only if configured in the session flow. | |
captureAttemptsLimit.max |
integer (int32) | Maximum number of attempts to capture a photo. | |
captureAttemptsLimit.remaining |
integer (int32) | Number of remaining attempts to capture a photo. | |
idQualityAttemptApproved |
boolean | ID quality check result based on ML readability estimation. True if perFieldReadability >= 0.38, false otherwise. Only available for Mexican documents when feature is enabled. | |
isDocumentExpired |
boolean | Flag indicating if the document side is expired. |
400
Custom error statuses:
- 1003: Face cropping failure
- 4004: Could not find user
- 4019: Face not found
Response body (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
timestamp |
integer (int64) | UTC timestamp in milliseconds | |
status |
integer (int32) | Custom error code or HTTP status code | |
error |
string | HTTP status error | |
message |
string | Custom error message | |
path |
string | Endpoint path | |
details |
object | Custom error details |