Responses

Encyption and Decryption

1Kosmos's API responses are encrypted using Elliptic Curve Digital Signature Agorithm (ECDSA) to ensure secure data transmission.

ID Verification Responses

The response displays the generated session URL in the encrypted format. After the document verification API execution is successful, click the Visualization tab in the response to view the result in the decrypted format. Otherwise, you can use your own helper that is compatible with ECDSA to view the result in the decrypted format.

Create Session API

This API is used to create a session for a specific document type. You can generate a session with one of the supported documents.

• idcard
• driving license
• passport

The response is displayed in the decrypted format:

Sample Success Response

note

If you pass an incorrect dvcID to your request body, you would encounter the 404 Not Found error. The following screenshot illustrates the same:

Scenario1: Incorrect dvcID

If you fail to pass the dvcID to your request body, you would encounter the 400 Bad Request error. The following screenshot illustrates the same:

Scenario 2: dvcID is blank

ID Verification Status

1Kosmos's ID Verification has the following types of statuses:

• Session Status
  • Pending
  • In Progress
  • Completed
  • Expired
  • Declined
• Verification Status
  • Failed
  • Passed
  • Not performed

The table below outlines the scenarios in which each session status is shown:

When a	the session status will be
Session has been created for a user and has not yet started the verification process	Pending
User clicks on the consent check box and hit “Let’s get started”	In Progress
User submits the document and gives selfie (if session is configured for selfie)	Completed
Session has expired	Expired
User click the Decline button on the Welcome screen	Declined

Poll API

The /result API displays the complete session details along with the verification status in encrypted format. To view the results in the decrypted format, click the Visualization tab in the response section when you run this API in your postman. Otherwise, you can use your own helper that is compatible with ECDSA to view the result in the decrypted format.

The following section outlines the various verification statuses:

In Progress

Sample Encrypted Response

Sample Decrypted Response

Decrypted Response parameters

The following parameters are returned in the response:

Parameter	Type	Description
sessionResult	string	Status of the verification result. Displays the status as In Progress.
sessionID	string	session ID.

Success

Sample Encrypted Response

Sample Decrypted Response

Decrypted Response parameters

The following parameters are returned in the response:

Parameter	Type	Description
sessionResult	string	Status of the verification result. Displays the status as Success
sessionID	string	session ID
username	string	name of the user for whom the verification was performed
firstname	string	first name of the user for whom the verification was performed
lastname	string	last name of the user for whom the verification was performed
documentType	string	Document that was used during verification
documentId	string	ID of the document
doe	integer	Expiry date of the document
category	string	Category to which the document belongs
country	string	country to which the user belongs as per the document
state	string	state to which the user belongs as per the document
image	string	image from the user's identity document
imageBack	string	Back image from the user's identity document
familyName	string	sur name of the user retrieved from the identity document
complianceType	string	Gender of the user
city	string	city to which the user belongs as per the document
street	string	street to which the user belongs as per the document
residenceZipCode	integer	zip code state to which the user belongs as per the document
dob	integer	user's date of birth as per the document

Failed

Sample Encrypted Response

Sample Decrypted Response

Decrypted Response parameters

The following parameters are returned in the response:

Parameter	Type	Description
sessionResult	string	Status of the verification result. Displays the status as Failed
sessionID	string	session ID
firstname	string	first name of the user for whom the verification was performed
lastname	string	last name of the user for whom the verification was performed
documentType	string	Document that was used during verification
documentId	string	ID of the document
firstName	string	First name as in the extracted document
lastName	string	Last name as in the extracted document
doe	integer	Expiry date of the document
message	string	Error message
reason_code	string	Reason code for failed status
reason	string	Reason for failed verification status

Error codes

The following table provides information on error codes:

Error Code	Description	Recommendation
IDV0001	Image quality check failed	Helpdesk administrators need to create a new session for the user.
IDV0002	Verification partially completed	Helpdesk administrators need to create a new session for the user.
IDV0003	Verification was completed only on front	Helpdesk administrators need to create a new session for the user.
IDV0004	Extraction of document failed	Helpdesk administrators need to create a new session for the user.
IDV0005	Incorrect document type presented	User must present a valid document for which the session is created. For instance, if a session is created for a Driving License but the user presents a passport instead, they will see an error message indicating the incorrect document type. In this case, if a session is created for a DL, the user must only present their DL.
IDV0006	Unsupported document was presented	1Kosmos has a list of supported documents. Use one of them based on your location and re-initiate the session.
IDV0007	Data check failed	Upload the correct document and re-initiate the session.
IDV0008	Document liveness check failed	The document liveness check failed. For instance, the user submitted a photocopy of the document.
IDV0009	Document validity check failed	This occurs when multiple fraud checks are conducted, including document liveness, fraud detection, selfie liveness, and selfie-to-headshot comparison. If a failure is encountered, please provide a valid document.
IDV00010	Module '$module' failed	User who is verifying their identity has to upload their own document.
IDV00011	Document expired	Upload a non-expired document.
IDV00012	One or more fraud check failed	Upload a valid document.