GIDX: DocumentInsight

Home / API Reference
Code Samples Coming Soon... C# PHP Python

API Integration: DocumentInsight

Overview

The Document Insight API, powered by Veriff, provides an AI-powered, automated solution for verifying a customer's ID document.

How it works

  • Make a CreateSession API call, which returns a URL.
  • Open that URL for the customer, or use one of Veriff's SDKs to embed it.
  • Wait for the callback. If the DOC-VERIFIED reason code is returned, the customer has been verified.

Sandbox Testing

Pass your desired result in the ReasonCode property of the CreateSession request. Either DOC-VERIFIED, or DOC-FAIL.

GIDX Platform DocumentInsight API Method Reference

Below are descriptions of the methods exposed by the GIDX Platform DocumentInsight Service.

https://api.gidx-service.in/v3.0/api/DocumentInsight
https://api.gidx-service.in/v3.0/api/DocumentInsight
https://api.gidx-service.in/v3.0/api/DocumentInsight

DocumentInsight: Request & Response Parameter Constants

The following parameters are used in every DocumentInsight Method Request and Responses. They are labeled within the methods below as Standardized Request Parameters and Standardized Response Parameters.

Making a Request
Each API method has a corresponding Request object used to transport the request parameters as shown below.

Using the Response
Each Response object returned from the method Request will contain properties you can use to determine the status of the methods service. Use the IsSuccess property along with the ResponseCode and ResponseMessage values to detect if the Request completed without a problem.

Standardized Request Parameters

ApiKey
String Required
Your assigned ApiKey, provided to you by the GIDX team.
4QhgWWJxRlqVctrc7SxHEQ
MerchantID
String Required
Your assigned Merchant ID, provided to you by the GIDX team.
VpGYLoXhSS+WgU9N415IJQ
ProductTypeID
String Required
Your assigned ID for merchant product type.
Fc+k5kRDSAOrh38e21vt0w
DeviceTypeID
String Required
Your assigned ID for this specific customer device type.
m+2XHlcIR0O1C+iBeNzfvA
ActivityTypeID
String Required
Your assigned ID for this specific customer activity type.
VV4XTc3tRi6g1EYLOazn0g
MerchantSessionID
String Required
A unique SessionID from your system assigned to this active session.
xHhSS+WglqVctrc7-t7SEQrc

Standardized Response Parameters

ApiKey
String Echo
Echo of your assigned ApiKey that you provided in the request.
4QhgWWJxRlqVctrc7SxHEQ
MerchantID
String Echo
Echo of your assigned Merchant ID that you provided in the request.
VpGYLoXhSS+WgU9N415IJQ
MerchantSessionID
String Echo
Echo of your unique SessionID for this active session that you provided in the request.
xHhSS+WglqVctrc7-t7SEQrc
ResponseCode
Integer
Response code for the method call. This will be 0 if there are no issues, non-zero otherwise.
0
ResponseMessage
String
Readable text message corresponding to the response code.
No Errors
https://api.gidx-service.in/v3.0/api/DocumentInsight
https://api.gidx-service.in/v3.0/api/DocumentInsight

CreateSession

Call this method to start a document verification session.

Request Type:
HTTP POST: JSON
Parameters:
CreateSessionRequest (object)
Return Value:
CreateSessionResponse (object)
Endpoint URL:
https://api.gidx-service.in/v3.0/api/DocumentInsight/CreateSession

CreateSessionRequest

Standardized Parameters
Standard Request
See the Standardized Paramaters above.
MerchantCustomerID
String Required
Your unique ID for this customer.
ABC-123
CallbackURL
String Required
https://yourserver.com/GidxCallback
When the session is complete or expires, we will send a request to this URL. You can check the reason codes for DOC-VERIFIED to see if the session was successful.
RedirectURL
String Optional
https://yourserver.com/GidxRedirect
The page to redirect the user back to after they complete the session.
CustomerRegistration
Object CustomerIdentity: CustomerRegistrationRequest
Optional - See CustomerRegistrationRequest
CustomerRegistrationRequest Object
You can provide any information you have on the customer here. If the information provided does not match what is on their ID, the session will be unsuccessful.
ReasonCode
String Optional
For sandbox testing, pass the reason code you want to simulate.
DOC-VERIFIED

CreateSessionResponse

Standardized Parameters
Standard Response
See the Standardized Paramaters above.
SessionURL
String
The Veriff URL to send the user to.
ReasonCodes
Array
Initial reason codes for this session. More will be added as the session continues.
https://api.gidx-service.in/v3.0/api/DocumentInsight
https://api.gidx-service.in/v3.0/api/DocumentInsight

SessionStatus

Call this API at anytime to get the information on a specific session.

Request Type:
HTTP GET: Query String
Parameters:
SessionStatusRequest (object)
Return Value:
SessionStatusResponse (object)
Endpoint URL:
https://api.gidx-service.in/v3.0/api/DocumentInsight/SessionStatus

SessionStatusRequest

Standardized Parameters
Standard Request
See the Standardized Paramaters above.
MerchantSessionID
String Required
The ID you passed to CreateSession.
ABC-123

SessionStatusResponse

Standardized Parameters
Standard Response
See the Standardized Paramaters above.
MerchantSessionID
String Echo
Echo of your ID for this session.
ABC-123
SessionURL
String
The Veriff URL to send the user to.
SessionStatusCode
Integer
The status of the session.
0
ReasonCodes
Array
The reason codes for this session. Look for DOC-VERIFIED or DOC-FAIL.
["DOC-VERIFIED"]
Files
Array
A list of image files that were created for this session.
VeriffDecision
Object
The Veriff verification object.
See Veriff's API docs for the verification object's specifications.

DocumentInsight: Callback

Receiving callbacks from GIDX
When a session's status is changed, a callback will be made to the CallbackURL you provided in CreateSession. The callback will be an HTTP POST with a JSON request body. An example of the callback JSON is on the right side of this page.
Responding to callbacks
You must respond to the callback with an HTTP 200 status code, or we will retry the callback up to 5 times over the next 2 hours.

DocumentInsightCallback

Standardized Parameters
Standard Response
See the Standardized Paramaters above.
StatusCode
Integer
The status of the session.
0
StatusMessage
String
Readable text message corresponding to the status code.
Document Insight Session is Complete.
MerchantSessionID
String Echo
Echo of your unique ID for this session.
ABC-123
ReasonCodes
Array
The reason codes for this session.
["DOC-VERIFIED"]
SessionID
String
Unique ID in the GIDX system for this session.
xHhSS+WglqVctrc7-t7SEQrc
ServiceType
String
Document Insight
//Example Callback - DocumentInsight { "StatusCode": 0, "StatusMessage": "Document Insight Session is Complete.", "SessionID": "X9XeW5FvCEKimOKw59GNPA", "MerchantSessionID": "ABC-123", "ReasonCodes": ["DOC-VERIFIED"], "ServiceType": "Document Insight" }
https://api.gidx-service.in/v3.0/api/DocumentInsight
https://api.gidx-service.in/v3.0/api/DocumentInsight

Response Object Reference

The Object documented below are returned within the Response of Method Request within the GIDX Platform DocumentInsight Services. When applicable an Object may be shared by among other Method Responses as indicated in the listings below.

Objects are always returned in JSON format.

Object: File

This object contains information on an image file that was created during the session.

Returned in Response:
SessionStatusResponse
Property Name
Description / Data Type
Example
FileID
String
A unique ID for this file.
456-ABC-123
CategoryType
Int
The category that best describes the type of document that is an image of.
See CategoryType Listing
Side
String
The side of the document this is an image of. Front or Back
Front
FileName
String
A generated name for the file.
document-front.jpg
FileSize
Int
The size of the file in bytes.
1025698
ContentType
String
The MIME type of the file.
image/jpeg

Appendix Library: Code / Status Index

The information documented below provides clarification of the codes used within the GIDX Platform DocumentInsight Services.

Appendix Library: Response Codes & Messages

Code
Message / Description
0
Good - Successful Response
500
General Error - Unknown Response Error
501
Invalid Request - Incorrect Request Format or Access Status
502
Unauthorized Request - Security Block of Request

Appendix Library: Session Status Codes

Code
Message / Description
0
Complete - The session is complete. This does not indicate success, look for DOC-VERIFIED or DOC-FAIL reason codes instead.
1
Ineligible - The customer is not eligible for a Document Insight session.
2
Incomplete - The customer abandoned the session.
3
Timeout - The Veriff session has expired. Sessions expire after 7 days.
4
In Progress - The session is currently active.

Appendix Library: CategoryTypes

Code
Description / Source
1
Other
2
Drivers License
3
Passport
4
Military ID
5
Govt. Issued Photo ID
6
Student Photo ID
7
Utility Bill
8
Selfie

Appendix Library: Data & System Reference

ISO 2 Digit Country Code

ISO 3166-1 is part of the ISO 3166 standard published by the International Organization for Standardization (ISO), and defines codes for the names of countries, dependent territories, and special areas of geographical interest.
http://en.wikipedia.org/wiki/ISO_3166-1

ISO 2 Digit U.S. State Codes

ISO 3166-2:US is the entry for the United States in ISO 3166-2, part of the ISO 3166 standard published by the International Organization for Standardization (ISO), which defines codes for the names of the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1.
http://en.wikipedia.org/wiki/ISO_3166-2:US

ReasonCodes

For the latest list of Reason Codes and their description please go to the following URL.
View Reason Codes