Retrieving a Verification Result

To retrieve the results of a verification session, you can call the /v2/session/{sessionId}/decision/ endpoint.

Base URL: https://verification.didit.me
Endpoint: /v2/session/{sessionId}/decision/
Method: GET
Authentication: Client Token (Bearer Token)

⚠️

The authentication endpoint uses a different base URL than the verification session endpoints. Ensure you use the correct URLs to avoid connectivity issues.

Request

Follow these steps to retrieve a verification result programmatically:

Step 1: Authenticate

Obtain a valid access_token by following the Authentication documentation. This token is required in the Authorization header of your request.

ℹ️

The access_token is valid for 24 hours. You only need to re-authenticate once it expires.

Step 2: Prepare Request Parameters

Parameter	Type	Required?	Description	Example Value
`session_id`	`string`	Yes	The unique identifier of the session for which to retrieve verification results.	`"11111111-2222-3333-4444-555555555555"`

Step 3: Send the Request

Make a GET request to /v2/session/{session_id}/decision/ with the access token in the Authorization header.

Example Request

GET /v2/session/11111111-2222-3333-4444-555555555555/decision/ HTTP/1.1
Host: verification.didit.me
Content-Type: application/json
Authorization: Bearer {access_token}

Response

The response provides detailed information about the verification session, including KYC, AML, facial recognition results, address verification, warnings, and reviews.

Example Response

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "session_url": "https://verify.didit.me/session/11111111-2222-3333-4444-555555555555",
  "status": "In Review",
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "features": ["ID_VERIFICATION", "NFC", "LIVENESS", "FACE_MATCH", "POA", "PHONE", "AML", "IP_ANALYSIS"],
  "vendor_data": "11111111-1111-1111-1111-111111111111",
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "callback": "https://verify.didit.me/",
  // optional field if ID_VERIFICATION feature is enabled
  "id_verification": {
    "status": "Approved",
    "document_type": "Identity Card",
    "document_number": "CAA000000",
    "personal_number": "99999999R",
    "portrait_image": "https://example.com/portrait.jpg",
    "front_image": "https://example.com/front.jpg",
    "front_video": "https://example.com/front.mp4",
    "back_image": "https://example.com/back.jpg",
    "back_video": "https://example.com/back.mp4",
    "full_front_image": "https://example.com/full_front.jpg",
    "full_back_image": "https://example.com/full_back.jpg",
    "date_of_birth": "1980-01-01",
    "age": 45,
    "expiration_date": "2031-06-02",
    "date_of_issue": "2021-06-02",
    "issuing_state": "ESP",
    "issuing_state_name": "Spain",
    "first_name": "Carmen",
    "last_name": "Española Española",
    "full_name": "Carmen Española Española",
    "gender": "F",
    "address": "Avda de Madrid 34, Madrid, Madrid",
    "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
    "place_of_birth": "Madrid",
    "marital_status": "Single",
    "nationality": "ESP",
    "parsed_address": {
      "id": "7c6280a2-fb6a-4258-93d5-2ac987cbc6ba",
      "city": "Madrid",
      "label": "Spain ID Card Address",
      "region": "Madrid",
      "street_1": "Avda de Madrid 34",
      "street_2": null,
      "postal_code": "28822",
      "raw_results": {
        "geometry": {
          "location": {
            "lat": 37.4222804,
            "lng": -122.0843428
          },
          "location_type": "ROOFTOP",
          "viewport": {
            "northeast": {
              "lat": 37.4237349802915,
              "lng": -122.083183169709
            },
            "southwest": {
              "lat": 37.4210370197085,
              "lng": -122.085881130292
            }
          }
        },
      },
    },
    "extra_files": [
      "https://example.com/extra_id_verification.jpg",
    ],
    "warnings": [
      {
        "risk": "QR_NOT_DETECTED",
        "additional_data": null,
        "log_type": "information",
        "short_description": "QR not detected",
        "long_description": "The system couldn't find or read the QR code on the document, which is necessary for document verification. This could be due to poor image quality or an unsupported document type.",
      }
    ],
  },
  // optional field if NFC feature is enabled
  "nfc": {
    "status": "In Review",
    "portrait_image": "https://example.com/portrait.jpg",
    "signature_image": "https://example.com/signature.jpg",
    "chip_data": {
      "document_type": "ID",
      "issuing_country": "ESP",
      "document_number": "123456789",
      "expiration_date": "2030-01-01",
      "first_name": "John",
      "last_name": "Smith",
      "birth_date": "1990-05-15",
      "gender": "M",
      "nationality": "ESP",
      "address": "CALLE MAYOR 123 4B, MADRID, MADRID",
      "place_of_birth": "MADRID, MADRID"
    },
    "authenticity": {
      "sod_integrity": true,
      "dg_integrity": true
    },
    "certificate_summary": {
      "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
      "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
      "serial_number": "118120836164494130086420187336801405660",
      "not_valid_after": "2031-02-18 10:21:11",
      "not_valid_before": "2020-11-18 10:21:11"
    },
    "warnings": [
      {
        "risk": "DATA_INCONSISTENT",
        "additional_data": null,
        "log_type": "warning",
        "short_description": "OCR and NFC mrz code extracted are not the same",
        "long_description": "The Optical Character Recognition (OCR) data and the NFC chip data don't match, indicating potential document tampering or data inconsistency."
      }
    ],
  },
  // optional field if LIVENESS feature is enabled
  "liveness": {
    "status": "Approved",
    "method": "ACTIVE_3D",
    "score": 89.92,
    "reference_image": "https://example.com/reference.jpg",
    "video_url": "https://example.com/video.mp4",
    "age_estimation": 24.3,
    "warnings": [
      {
        "risk": "LOW_LIVENESS_SCORE",
        "additional_data": null,
        "log_type": "information",
        "short_description": "Low liveness score",
        "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data."
      }
    ]
  },
  // optional field if FACE_MATCH feature is enabled
  "face_match": {
    "status": "In Review",
    "score": 65.43,
    "source_image": "https://example.com/source-image.jpg",
    "target_image": "https://example.com/target-image.jpg",
    "warnings": [
      {
        "risk": "LOW_FACE_MATCH_SIMILARITY",
        "additional_data": null,
        "log_type": "warning",
        "short_description": "Low face match similarity",
        "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch."
      }
    ]
  },
  // optional field if PHONE feature is enabled
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+34",
    "phone_number": "600600600",
    "full_number": "+34600600600",
    "country_code": "ES", // ISO 3166-1 alpha-2
    "country_name": "Spain",
    "carrier": {
      "name": "Orange",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "sms",
    "verification_attempts": 1,
    "verified_at": "2024-07-28T06:47:35.654321Z",
    "warnings": [],
  },
  // optional field if POA feature is enabled
  "poa": {
    "status": "Approved",
    "document_type": "Bank Statement",
    "issuer": "National Bank",
    "issue_date": "2024-05-15",
    "document_language": "EN",
    "name_on_document": "John A. Smith",
    "name_match_score": 92.5,
    "address": "123 Main St, Apartment 4B, New York, NY 10001",
    "formatted_address": "123 Main St, Apartment 4B, New York, NY 10001, USA",
    "parsed_address": {
      "street_1": "123 Main St",
      "street_2": "Apartment 4B",
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "raw_results": {
        "geometry": {
          "location": {
            "lat": 40.7128,
            "lng": -74.0060
          }
        }
      }
    },
    "document_file": "https://example.com/poa_document.pdf",
    "extra_files": [
      "https://example.com/extra_poa.pdf",
    ],
    "warnings": [],
  },
  // optional field if AML feature is enabled
  "aml": {
    "status": "In Review",
    "total_hits": 1,
    "hits": [
      {
        "id": "cl-info-probidad-3fd0f04facc53bd94ebec9aaedf56d18",
        "match": false,
        "score": 0.4,
        "target": true,
        "caption": "PABLO ALFONSO ESCOBAR NAVARRO",
        "datasets": ["cl_info_probidad"],
        "features": {
          "country_mismatch": 1.0,
          "person_name_phonetic_match": 0.67
        },
        "last_seen": "2024-10-28T02:50:03",
        "first_seen": "2024-01-17T02:50:01",
        "properties": {
          "name": ["PABLO ALFONSO ESCOBAR NAVARRO"],
          "topics": ["role.pep"],
          "country": ["cl"]
        }
      }
    ],
    "score": 40.0,
    "screened_data": {
      "full_name": "Pablo Escobar",
      "nationality": "COL",
      "date_of_birth": "1975-12-01",
      "document_number": "CAA000000"
    },
    "warnings": [
      {
        "risk": "POSSIBLE_MATCH_FOUND",
        "additional_data": null,
        "log_type": "warning",
        "short_description": "Possible match found in AML screening",
        "long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review."
      }
    ],
  },
  // optional field if IP_ANALYSIS feature is enabled
  "ip_analysis": {
      "status": "Approved",
      "device_brand": "Apple",
      "device_model": "iPhone",
      "browser_family": "Mobile Safari",
      "os_family": "iOS",
      "platform": "mobile",
      "ip_country": "Spain",
      "ip_country_code": "ES",
      "ip_state": "Barcelona",
      "ip_city": "Barcelona",
      "latitude": 41.4022,
      "longitude": 2.1407,
      "ip_address": "83.50.226.71",
      "isp": null,
      "organization": null,
      "is_vpn_or_tor": false,
      "is_data_center": false,
      "time_zone": "Europe/Madrid",
      "time_zone_offset": "+0100",
      "locations_info": {
          "ip": {
            "location": {"latitude": 40.2206327, "longitude": 1.5770097},
            "distance_from_id_document": 23.4,
            "distance_from_poa_document": 12.3
          },
          "id_document": {
              "location": {"latitude": 41.2706327, "longitude": 1.9770097},
              "distance_from_ip": 23.4,
              "distance_from_poa_document": 18.7,
          },
          "poa_document": {
            "location": {"latitude": 41.2706327, "longitude": 1.9770097},
            "distance_from_ip": 12.3,
            "distance_from_id_document": 18.7
          },
      },
      "warnings": [],
  },
  "reviews": [
    {
      "user": "compliance@example.com",
      "new_status": "Declined",
      "comment": "Possible match found in AML screening",
      "created_at": "2024-07-18T13:29:00.366811Z"
    }
  ],
  "created_at": "2024-07-24T08:54:25.443172Z"
}

This response example is for a KYC workflow type which includes ID verification, Liveness, Face Match, IP Analysis, Phone Verification, Proof of Address, and AML screening. You can learn more about available workflows in the Verification Workflows documentation.

Response Fields

Field	Type	Description
`session_id`	`string`	Unique identifier for the session.
`session_number`	`number`	Sequential number assigned to the session.
`session_url`	`string`	URL where the verification session can be accessed.
`status`	`string`	Current session status (e.g., "Approved", "Declined", "In Review"). Check all the possible statuses in the Verification Statuses documentation.
`workflow_id`	`string`	ID of the workflow used for this session.
`vendor_data`	`string`	Vendor-specific identifier provided during session creation.
`metadata`	`object`	Custom metadata provided during session creation.
`callback`	`string`	Callback URL provided during session creation.
`kyc`	`object`	KYC (Know Your Customer) verification results, including document data.
`liveness`	`object`	Liveness detection results, including method, age estimation, gender estimation, and score.
`face_match`	`object`	Face matching results between document and selfie.
`ip_analysis`	`object`	IP analysis results, including IP address, device information, and geographical coordinates.
`phone`	`object`	Phone verification results, including carrier information and risk assessment.
`poa`	`object`	Proof of Address verification results, including document details and address parsing.
`aml`	`object`	AML (Anti-Money Laundering) screening results, if applicable.
`reviews`	`array`	History of manual reviews performed on the session.
`extra_files`	`array`	Additional images collected during the verification process.
`created_at`	`string`	Timestamp when the session was created (ISO 8601 format).

Error Handling

Status Code	Error	Description
`401`	Unauthorized	Invalid or missing access_token.
`404`	Not Found	Session ID not found or invalid.
`403`	Forbidden	Not authorized to access this session's data.

Example Error Response

{
  "detail": "Session not found."
}

Using the Verification Data

The verification result provides comprehensive data that can be used for:

User Onboarding: Determine if a user should be approved or requires further review
Risk Assessment: Evaluate potential risks based on warnings and AML screening
Compliance Records: Store necessary user identification data for regulatory compliance
User Profile Creation: Use extracted data to pre-fill user profiles in your system

When storing verification data, ensure compliance with relevant data protection regulations like GDPR. Only store what is necessary for your legitimate business purposes.

Code Examples

const getSessionDecision = async (sessionId) => {
  const endpoint = `https://verification.didit.me/v2/session/${sessionId}/decision/`;
  const token = await getClientToken();
 
  if (!token) {
    console.error('Error fetching client token');
    throw new Error('Authentication failed');
  }
 
  const headers = {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token.access_token}`,
  };
 
  try {
    const response = await fetch(endpoint, {
      method: 'GET',
      headers,
    });
 
    if (!response.ok) {
      const errorData = await response.json();
      console.error('Error fetching session decision:', errorData.detail || errorData.message);
      throw new Error(errorData.detail || 'Failed to retrieve session data');
    }
 
    const data = await response.json();
    return data;
  } catch (err) {
    console.error('Error:', err);
    throw err;
  }
};

Implementing Verification Logic

Below is a simple example of how to process verification results in your application:

async function processVerificationResult(sessionId) {
  try {
    const sessionData = await getSessionDecision(sessionId);
 
    // Check overall status
    if (sessionData.status === 'Approved') {
      // Process approved user
      await approveUserInYourSystem(sessionData.vendor_data);
 
      // Store necessary KYC data
      const userData = {
        firstName: sessionData.kyc.first_name,
        lastName: sessionData.kyc.last_name,
        dateOfBirth: sessionData.kyc.date_of_birth,
        documentNumber: sessionData.kyc.document_number,
        documentType: sessionData.kyc.document_type,
        address: sessionData.kyc.formatted_address,
        nationality: sessionData.kyc.nationality
      };
 
      await storeUserVerificationData(sessionData.vendor_data, userData);
 
      return {
        success: true,
        message: 'User verification approved',
        userId: sessionData.vendor_data
      };
    }
    else if (sessionData.status === 'In Review') {
      // Handle review cases
      await flagUserForReviewInYourSystem(sessionData.vendor_data);
      return {
        success: false,
        requiresReview: true,
        message: 'User verification pending review',
        userId: sessionData.vendor_data
      };
    }
    else {
      // Handle rejection
      const warnings = sessionData.warnings.map(w => w.short_description).join('; ');
      await rejectUserInYourSystem(sessionData.vendor_data, warnings);
      return {
        success: false,
        message: 'User verification declined',
        reasons: warnings,
        userId: sessionData.vendor_data
      };
    }
  } catch (error) {
    console.error('Error processing verification:', error);
    return {
      success: false,
      message: 'Error processing verification',
      error: error.message
    };
  }
}

Create Session Delete Session