Get User Verification

Overview

After creating a verification session and initiating the verification process, you may need to retrieve detailed information about a user's session. VOVE ID provides an endpoint for this purpose. This section outlines how to retrieve user's session information. This operation is typically triggered after the backend receives a webhook notification via our system.

---

Endpoint and Request

Base URL: https://api.voveid.com or https://api.voveid.net

Endpoint: GET /v2/users/:refId

Headers:

• Content-Type: application/json

• x-api-key: API_KEY

Path Parameters:

• refId The user identifier in your system.

Example Request:

GET /v2/users/3eb8c91c-c866-4fcb-9805-67e8b45c7883 HTTP/1.1
Content-Type: application/json
x-api-key: YOUR_API_KEY

Get User Session

On a successful request, the API will return detailed information about the user's session. An example response might look like this:

{
  "_id": "66f1f1dd3a091e401033b270",
  "refId": "F1A1B12C-4F32-43A2-BE72-9DAB8D4C6E2B",
  "status": "successful",
  "createdAt": "2024-09-23T22:55:25.894Z",
  "updatedAt": "2024-09-23T22:55:25.895Z",
  "flowId": "76g12d91a2836ecf43cdcb40",
  "sessionId": "76g12d91a2836ecf43cdcb46",
  "sessions": [
    "76g12d91a2836ecf43cdcb46"
  ],
  "documents": [
    {
      "stepId": VoveStepId.ID_DOCUMENT,
      "type": DocumentType,
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfExpiration": "15/07/2030",
      "address1": "1234 FAKE STREET, SPRINGFIELD",
      "dateOfIssue": "15/07/2020",
      "sex": "M",
      "dateOfBirth": "01/01/1990",
      "issuingAuthority": "SPRINGFIELD MUNICIPALITY",
      "placeOfBirth": "SPRINGFIELD",
      "mrzLine1": "P<USAJOHN<<DOE<<<<<<<<<<<<<<<<<<<<<<<<<<",
      "mrzLine2": "X12345678USA900101M3007155DOE<<<<<<<<<<",
      "idNumber": "X12345678",
      "matchLevel": 7
      "digitalIDSpoof": VoveDigitalIDSpoofStatusEnum;
      "faceOnDocumentSpoof": VoveFaceOnDocumentStatusEnum;
      "textOnDocumentSpoof": VoveTextOnDocumentStatusEnum;
      "mrzStatus"?: VoveMrzStatusEnum;
    },
    {
      "stepId": VoveStepId.DRIVER_LICENSE,
      "type": DocumentType,
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfIssue": "10/05/2015",
      "dateOfBirth": "01/01/1990",
      "idNumber": "DL987654321",
      "digitalIDSpoof": VoveDigitalIDSpoofStatusEnum,
      "faceOnDocumentSpoof": VoveFaceOnDocumentStatusEnum,
      "textOnDocumentSpoof": VoveTextOnDocumentStatusEnum,
      "mrzStatus": VoveMrzStatusEnum,
    },
    {
      "stepId": VoveStepId.ADDRESS_PROOF,
      "docTypes": ["UTILITY_BILL_ELECTRICITY"], // AddressProofType
      "fullName": "JOHN DOE",
      "issueDate": "10/05/2015",
      "issuerName": "Electric",
      "address": "Avenue John doe, DE, USA"
    }
  ],
  "metadata": [
    "203.0.113.5"
  ]
}

Types:

enum VoveStepId {
  ID_DOCUMENT = 'ID_DOCUMENT',
  DRIVING_LICENSE = 'DRIVING_LICENSE',
  CAR_REGISTRATION_DOCUMENT = 'CAR_REGISTRATION_DOCUMENT',
  ADDRESS_PROOF = 'ADDRESS_PROOF'
}
export enum VoveDigitalIDSpoofStatusEnum {
  LIKELY_PHYSICAL_ID = 'LIKELY_PHYSICAL_ID',
  COULD_NOT_CONFIDENTLY_DETERMINE_PHYSICAL_ID_USER_NEEDS_TO_RETRY = 'COULD_NOT_CONFIDENTLY_DETERMINE_PHYSICAL_ID_USER_NEEDS_TO_RETRY',
}

export enum VoveFaceOnDocumentStatusEnum {
  NOT_AVAILABLE = 'NOT_AVAILABLE',
  LIKELY_ORIGINAL_FACE = 'LIKELY_ORIGINAL_FACE',
  CANNOT_CONFIRM_ID_IS_AUTHENTIC = 'CANNOT_CONFIRM_ID_IS_AUTHENTIC',
  OCR_TEMPLATE_DOES_NOT_SUPPORT_DETECTION = 'OCR_TEMPLATE_DOES_NOT_SUPPORT_DETECTION',
}

export enum VoveTextOnDocumentStatusEnum {
  NOT_AVAILABLE = 'NOT_AVAILABLE',
  LIKELY_ORIGINAL_TEXT = 'LIKELY_ORIGINAL_TEXT',
  CANNOT_CONFIRM_ID_IS_AUTHENTIC = 'CANNOT_CONFIRM_ID_IS_AUTHENTIC',
}

export enum VoveMrzStatusEnum {
  NO_MRZ_SPECIFIED_BY_TEMPLATE = 'NO_MRZ_SPECIFIED_BY_TEMPLATE',
  MRZ_READ_BUT_CHECKSUM_FAILED = 'MRZ_READ_BUT_CHECKSUM_FAILED',
  SUCCESS = 'SUCCESS',
}

export enum DocumentType {
  Passport = "Passport",
  PassportCard = "Passport Card",
  DriverLicense = "Driver License",
  GovernmentIssuedPhotoId = "Government Issued Photo ID",
  CorporateIdBadge = "Corporate ID Badge",
  MedicalInsuranceCard = "Medical Insurance Card",
  VoterIdCard = "Voter ID Card",
  SchoolId = "School ID",
  CommercialDriverLicense = "Commercial Driver License",
  PilotLicense = "Pilot License",
  SocialSecurity = "Social Security",
  WorkPermit = "Work Permit",
  Other = "Other",
}

export enum AddressProofType {
  BANK_STATEMENT = 'BANK_STATEMENT',
  CREDIT_CARD_STATEMENT = 'CREDIT_CARD_STATEMENT',
  UTILITY_BILL_GAS = 'UTILITY_BILL_GAS',
  UTILITY_BILL_ELECTRICITY = 'UTILITY_BILL_ELECTRICITY',
  UTILITY_BILL_WATER = 'UTILITY_BILL_WATER',
  UTILITY_BILL_INTERNET = 'UTILITY_BILL_INTERNET',
  UTILITY_BILL_PHONE = 'UTILITY_BILL_PHONE',
  GOVERNMENT_CORRESPONDENCE = 'GOVERNMENT_CORRESPONDENCE',
  LEASE_AGREEMENT = 'LEASE_AGREEMENT',
  HOUSE_PURCHASE_DEED = 'HOUSE_PURCHASE_DEED',
  TAX_DOCUMENT = 'TAX_DOCUMENT',
  INSURANCE_DOCUMENT = 'INSURANCE_DOCUMENT',
  ID_WITH_ADDRESS = 'ID_WITH_ADDRESS',
  MORTGAGE_STATEMENT = 'MORTGAGE_STATEMENT',
  VOTER_REGISTRATION = 'VOTER_REGISTRATION',
  SOCIAL_SECURITY_STATEMENT = 'SOCIAL_SECURITY_STATEMENT',
  POSTMARKED_LETTER = 'POSTMARKED_LETTER',
  RENTAL_CONTRACT = 'RENTAL_CONTRACT',
  PAYSLIP = 'PAYSLIP',
  EMPLOYMENT_CONTRACT = 'EMPLOYMENT_CONTRACT',
}

Get session documents:

GET /v2/users/3eb8c91c-c866-4fcb-9805-67e8b45c7883/documents HTTP/1.1
Content-Type: application/json
x-api-key: YOUR_API_KEY

Example Response

On a successful request, the API will return detailed information about the user's session. An example response might look like this:

{
  "selfie": "base_64",
  "documents": [
    {
      "stepId": StepId.ID_DOCUMENT,
      "front": "base_64",
      "photo": "base_64",
      "frontCropped": "base_64",
      "backCropped": "",
      "type": DocumentType,
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfExpiration": "15/07/2030",
      "address1": "1234 FAKE STREET, SPRINGFIELD",
      "dateOfIssue": "15/07/2020",
      "sex": "M",
      "dateOfBirth": "01/01/1990",
      "issuingAuthority": "SPRINGFIELD MUNICIPALITY",
      "placeOfBirth": "SPRINGFIELD",
      "mrzLine1": "P<USAJOHN<<DOE<<<<<<<<<<<<<<<<<<<<<<<<<<",
      "mrzLine2": "X12345678USA900101M3007155DOE<<<<<<<<<<",
      "idNumber": "X12345678",
      "matchLevel": 7,
      "digitalIDSpoof": VoveDigitalIDSpoofStatusEnum,
      "faceOnDocumentSpoof": VoveFaceOnDocumentStatusEnum,
      "textOnDocumentSpoof": VoveTextOnDocumentStatusEnum;
      "mrzStatus": VoveMrzStatusEnum,
    },
    {
      "stepId": StepId.DRIVING_LICENSE,
      "front": "base_64",
      "back": "base_64",
      "photo": "base_64",
      "frontCropped": "base_64",
      "backCropped": "base_64",
      "type": DocumentType,
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfIssue": "10/05/2015",
      "dateOfBirth": "01/01/1990",
      "idNumber": "DL987654321",
      "digitalIDSpoof": VoveDigitalIDSpoofStatusEnum,
      "faceOnDocumentSpoof": VoveFaceOnDocumentStatusEnum,
      "textOnDocumentSpoof": VoveTextOnDocumentStatusEnum,
      "mrzStatus": VoveMrzStatusEnum
    },
     {
      "stepId": StepId.ADDRESS_PROOF,
      "docTypes": ["UTILITY_BILL_ELECTRICITY"],
      "fullName": "JOHN DOE",
      "issueDate": "10/05/2015",
      "issuerName": "Electric",
      "address": "Avenue John doe, DE, USA",
      "documentPath": "base64",
    }
  ],
}

Handling Webhook Notifications

When the verification process is completed or any specific event occurs, VOVE ID will send a webhook notification to your backend.. Upon receiving a webhook, your backend can trigger the retrieval of session information.

Step-by-Step Process:

1. Set Up Webhook Listener:

   • Configure your backend to listen for webhook notifications from us.

   • Ensure that your webhook endpoint can handle POST requests.

2. Receive Webhook Notification:

   • When a webhook is received, parse the payload to extract relevant information, using the refId.

3. Trigger Session Information Retrieval:

   • Use the refId to make a GET request to the GET /v2/users/:refId endpoint.

   • Include the API_KEY in the request header for authentication.

Example Code for Webhook Handling and Session Retrieval:

const express = require('express');
const axios = require('axios');

const app = express();
app.use(express.json());

app.post('/webhook', async (req, res) => {
  // refId is the ID you provided earlier to create the session
  const { refId } = req.body; // Extract refId from webhook payload

  try {
    // Retrieve session information
    const sessionInfo = await axios.get(`https://api.voveid.net/v2/users/${refId}`, {
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
      }
    });

    console.log('Session Information:', sessionInfo.data);

    // Process the session information as needed
    // ...

    res.status(200).send('Webhook received and session information retrieved successfully.');
  } catch (error) {
    console.error('Error retrieving session information:', error);
    res.status(500).send('Failed to retrieve session information.');
  }
});

// Start the Express server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

Note: If you’re still using userId from earlier implementations, it will still be included in the webhook payload for backward compatibility, but we recommend switching to refId, which is now the standard identifier.

---

Conclusion

By following the steps outlined in this section, clients can efficiently retrieve and handle user's session information in VOVE ID. This process ensures that all relevant data about the user's verification session is accessible and can be used to make informed decisions or further actions within the client's application.