Responses

Encryption and Decryption

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

ID Verification Request and 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.

You can create sessions for one of the following documents:

• Passport
• Driving License
• ID card

Request Body

The request body of the create session API must be in JSON format and should include the following parameters.

Field Name	Required Field	Type	Description
dvcID	Yes	string	The workflow name
tenantDNS	Yes	string	Specify the tenant name
communityName	Yes	string	Specify your community name
documentType	Yes	string	Specify the document type for which you want to generate a session
username	No	string	Specify the user for whom the session is created
firstname	No	string	Specify the first name of the user for whom the session is created
lastname	No	string	Specify the last name of the user for whom the session is created
uid	No	integer	A unique identifier which help in mapping the session ID to the user performing the verification

Response

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.

Request Body

The request body of the Poll API must be in JSON format and should include the following parameters:

Field Name	Required Field	Type	Description
dvcID	Yes	string	The workflow name
sessionID	Yes	string	Enter the session id generated in the create session API

Response

The following section outlines the different statuses and corresponding responses returned during the execution of the Poll API:

note

Personally identifiable information (PII) is returned only once for each unique session ID. Any subsequent calls to the Poll API using the same session ID will not include PII data.

• When pii_retention_off = false and pii_retention_ttl = -1, PII data is retained until the first Poll API call is received after the session is completed; it is then deleted immediately.
• When pii_retention_off = false and pii_retention_ttl = 0, PII data is retained for 7 days and is available via the Poll API during this period; it is deleted afterward.
• When pii_retention_off = false and pii_retention_ttl > 0, PII data is retained for the specified number of seconds and is accessible through the Poll API within that timeframe; after that, it is deleted.
• When pii_retention_off = true, PII data is deleted immediately upon session completion and is not returned in any subsequent Poll API responses.

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.

Abandoned

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 Abandoned
sessionId	string	Session ID

Verification Not Performed

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
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
type	string	Document that was used during verification
docType	string	Type of document that was used during verification
docId	string	ID of the document
status	integer	Error status code
message	string	Message that is displayed for not performing the verification
reason	string	Reason for not performing the verification
reasonCode	string	Reason code

Pending

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

Expired

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 Expired
sessionId	string	Session ID

Declined

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 Declined
sessionId	string	Session ID

Poll API (V3) Response with Selfie Verification

The following table outlines the response parameters returned when the selfie capture flow is enabled during Poll API execution.

Sample Encrypted Response

Sample Decrypted Response