LogoLogo
  • Platform Overview
  • 🗺️Guides
    • Getting Started
    • Users
      • Integrate the User SDK
      • Registration
      • Authentication
      • SDK Releases
      • API Reference
    • Entitlements
      • Administrative API
        • Integrating the Administrative API
        • Entitlement Definitions
        • Managing Entitlements Sets
        • Managing Entitlements Sequences
        • Managing User Entitlements
        • API Schema
      • End-user API
        • Integrate the Entitlements SDK
        • Redeeming Entitlements
        • Retrieving Entitlements
        • SDK Releases
        • API Reference
    • Sudos
      • Integrate the Sudo Profiles SDK
      • Sudo Entitlements
      • Manage Sudos
      • SDK Releases
      • API Reference
    • Telephony
      • Integrate the Telephony SDK
      • Manage Phone Numbers
      • Text Messaging
      • Voice Calling
      • Telephony Simulator
      • SDK Releases
      • API Reference
    • Email
      • Integrate the Email SDK
      • Email Entitlements
      • Manage Email Addresses
      • Sending & Receiving Email
      • Manage Email Folders
      • Draft Email Messages
      • Manage Email Address Blocklists
      • Email Address Public Information
      • Pagination
      • Caching
      • Configuration Data
      • Email Notifications
      • SDK Releases
      • API Reference
    • Decentralized Identity
      • Edge Agent
        • Relay SDK
          • Integrate the Relay SDK
          • Relay Entitlements
          • Manage Relay Postboxes
          • Manage Relay Messages
          • Receiving Messages
          • SDK Releases
        • Edge Agent SDK
          • Integrate the Edge Agent SDK
          • Agent Management
          • Manage Wallets
          • Establishing Connections
          • Manage Connections
          • Messaging
          • Manage DIDs
          • Accepting New Credentials
          • Manage Credentials
          • Present Credentials for Verification
          • Utilize Alternative Cryptography Providers
          • SDK Releases
          • Standards and Protocols
      • Cloud Agent
        • Cloud Agent Admin API
          • Integrate the Cloud Agent Admin API
          • Aries Interop Profile (AIP)
            • Connection Exchanges
            • Credential Exchanges
            • Proof Exchanges
          • Connections
          • Basic Messages
          • Credentials
            • Anoncreds Credentials
              • Schemas
              • Credential Definitions
            • W3C Credentials
          • Audit Logs
          • API Schema
          • Error Codes
          • Standards and Protocols
    • Virtual Cards
      • Integrate the Virtual Cards SDK
      • Virtual Cards Entitlements
      • Virtual Cards Transaction Velocity Constraints
      • Key Management
      • Manage Funding Sources
      • Manage Virtual Cards
      • Manage Transactions
      • Configuration Data
      • Pagination
      • Caching
      • SDK Releases
      • API Reference
    • Virtual Cards Simulator
      • Integrate the Virtual Cards Simulator SDK
      • Simulate Authorizations
      • Simulate Debits
      • Simulate Refunds
      • Simulate Reversals
      • Merchants and Currencies
      • SDK Releases
      • API Reference
    • Virtual Private Network
      • Integrate the VPN SDK
      • VPN Entitlements
      • Manage Servers
      • Manage Connection
      • Observe VPN Related Events
      • SDK Releases
      • API Reference
      • Frequently Asked Questions
    • Secure ID Verification
      • Integrate the Secure ID Verification SDK
      • List Supported Countries
      • Verify an Identity
      • Check Secure ID Verification Status
      • Use the Secure ID Verification Simulator
      • SDK Releases
      • API Reference
    • Password Manager
      • Integrate the Password Manager SDK
      • Accessing the Password Manager
      • Managing Password Vaults
      • Managing Password Vault Items
      • Vault Import and Export
      • Password Utilities
      • Password Manager Entitlements
      • Password Vault Security
      • SDK Releases
      • API Reference
    • Ad/Tracker Blocker
      • Integrate the Ad/Tracker Blocker SDK
      • Manage Rulesets
      • Blocking Ads and Trackers
      • Manage Exceptions
      • SDK Releases
      • API Reference
    • Site Reputation
      • Integrate the Site Reputation SDK
      • Use the Site Reputation SDK
      • SDK Releases
      • API Reference
  • 💡Concepts
    • Sudo Digital Identities
  • 🧱Development
    • Versioning
  • 🏢Administration
    • Admin Console Roles
  • ❓Get Help
    • Request a Demo
    • Report an Issue
Powered by GitBook
On this page
  • Verify Identity using Personally Identifiable Information
  • Determine if a Face Image is Required with ID Document Verification
  • Verify Identity using Identity Documents
  • Determine if a Face Image is Required with ID Document Capture
  • Capture and Verify Identity Document
  1. Guides
  2. Secure ID Verification

Verify an Identity

Collect and verify identity information, and process the results.

Verify Identity using Personally Identifiable Information

Verify identity using the name, address and date of birth provided by a user. This information is verified using trusted data sources.

do {
    let input = VerifyIdentityInput(
        firstName: firstName, 
        lastName: lastName, 
        address: address, 
        city: city, 
        state: state, 
        postalCode: postalCode, 
        country: country, 
        dateOfBirth: dateOfBirth
    )
    let verifiedIdentity = try await identityVerificationClient.verifyIdentity(
        input: input
    )
    if verifiedIdentity.verified {
        // Identity verified succcessfully.
    } else {
        // Identity could not be verified.
    }
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
val input = VerifyIdentityInput(
    firstName = "John",
    lastName = "Smith",
    address = "222333 Peachtree Place",
    city = "Atlanta",
    state = "GA",
    postalCode = "30318",
    country = "US",
    dateOfBirth = "1975-02-28"
)
launch {
    try {
        val verifiedIdentity = withContext(Dispatchers.IO) {
            identityVerificationClient.verifyIdentity(
                input
            ) 
        }
        // The returned [verifiedIdentity] result has been verified.
    } catch (e: SudoIdentityVerificationException) {
        // Handle errors.
    }
}
try {
    const verifiedIdentity = await identityVerificationClient.verifyIdentity({
        firstName: 'John',
        lastName: 'Smith',
        address: '222333 Peachtree Place',
        city: 'Atlanta',
        state: 'GA',
        postalCode: '30318',
        country: 'US',
        dateOfBirth: '1975-02-28',
    })

    if (verifiedIdentity.verified) {
        // proceed to the next stage of the app
    }
    else {
        if (verifiedIdentity.canAttemptVerificationAgain) {
            // user is permitted to try again
        }
        else {
            if (verifiedIdentity.requiredVerificationMethod === 'GOVERNMENT_ID') {
                // can attempt verification with government issued
                // identity documents.
            }
            else {
                // maximum retries exceeded, or the reason for failed 
                // verification prevents retry, e.g. PII is of a deceased
                // person.
            }
        }
    }
}
catch (err) {
    // Handle errors
}
  • Name and address fields are case-insensitive.

  • City and state are optional fields.

  • The country value must be an ISO 3166-1 alpha-2 code returned from the listSupportedCountries() API.

  • The format required for dateOfBirth is yyyy-mm-dd

As well as returning a boolean indicator of the result of identity verification, the verified identity also provides the following information about the state of the identity verification attempt:

  • The verificationMethod property indicates the level of identity verification achieved for this user. Possible values are NONE, KNOWLEDGE_OF_PII and GOVERNMENT_ID.

  • For successfully verified identities, the verifiedAtEpochMs property specifies when verification succeeded. Where verification is not successful, the property will be set to 0 and can be ignored.

  • The verificationLastAttemptedAtEpochMs property specifies when the user last attempted identity verification, irrespective of whether verification was successful or not. For a user where identity verification has never been attempted, or where identity verification has not been attempted since an administrative reset of their identity verification status, the value will be 0.

  • The requiredVerificationMethod property indicates the level of identity verification required for this user in order to successfully complete identity verification. Different Sudo Platform environments may have different minimum required levels as well as cases where some users may require to achieve a higher level of verification, either to unlock greater entitlements or to manage risk.

  • The canAttemptVerificationAgain property indicates whether the Sudo Platform will accept new identity verification attempts for this user. This property will be set to false if the configured maximum number of retries is exceeded or earlier verification results do not permit retries to mitigate the risk of fraud, e.g. providing the PII of a deceased person.

  • In Sudo Platform environments performing identity verification against live data sources, the idScanUrl property provides a link to a web page where a user can interactively take photos of their government issued identity documents and upload them for verification.

The requiredVerificationMethod and canAttemptVerificationAgain properties can be used in a client application to guide a user's identity verification journey. For example, an application might attempt to verify using PII until achieving success, or canAttemptVerificationAgain is set to false. In the latter case, if the requiredVerificationMethod is set to GOVERNMENT_ID, the user could be directed to upload their id document, either via the verifyIdentityDocument API described below, or by rendering the web page indicated by the idScanUrl property described above.

When requiredVerificationMethod is returned set to GOVERNMENT_ID, the acceptableDocumentTypes list will be set to the list of document types that can be accepted to verify the user's identity.

Once the user's identity has been verified successfully the verification status, including verification method, is persisted on the user record in Sudo Platform and the user is not required to verify their identity again.

Determine if a Face Image is Required with ID Document Verification

To check if a face image must be provided along with ID document at the time of document verification (see verifyIdentityDocument method described below):

do {
    let faceImageRequired = try await identityVerificationClient.isFaceImageRequiredWithDocumentVerification(option: .remoteOnly)
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
CoroutineScope(Dispatchers.IO).launch {
    try {
        val faceImageRequired = identityVerificationClient.isFaceImageRequiredWithDocumentVerification()
    } catch (e: SudoIdentityVerificationException) {
        // Handle errors.
    }
}
try {
  const faceImageRequired = await identityVerificationClient.isFaceImageRequiredWithDocumentVerification()
}
catch (err) {
  // Handle errors
}

The isFaceImageRequiredWithDocumentVerification() API returns a boolean value.

Verify Identity using Identity Documents

Verify identity by validating images of a driver's license, passport or other government issued identity document.

Before a user's identity can be verified using identity documents, they must first attempt identity verification using personally identifiable information (see the API above).

do {
    let verifiedIdentity = try await identityVerificationClient.verifyIdentityDocument(
        input: VerifyIdentityDocument(
            image: frontImage, 
            backImage: backImage,
            faceImage: faceImage, // only include if required
            country: country,
            documentType: .driverLicense
        )
    )
    if verifiedIdentity.verified {
        // Identity verified succcessfully.
    } else {
        // Identity could not be verified.
    }
} catch {
    // Handle error.
}
val input = VerifyIdentityDocumentInput(
    documentType = IdDocumentType.driverLicense,
    country = "US",
    imageBase64 = encodedDocumentFrontImage,
    backImageBase64 = encodedDocumentBackImage
    faceImageBase64: encodedFaceImage, // only include if required
)
launch {
    try {
        val verifiedIdentity = withContext(Dispatchers.IO) {
            identityVerificationClient.verifyIdentityDocument(
                input
            ) 
        }
        // The returned [verifiedIdentity] result has been verified.
    } catch (e: SudoIdentityVerificationException) {
        // Handle errors.
    }
}
try {
  const verifiedIdentity = await identityVerificationClient.verifyIdentityDocument({
    documentType: IdDocumentType.driverLicense,
    country: 'US',
    imageBase64: encodedDocumentFrontImage,
    backImageBase64: encodedDocumentBackImage,
    faceImageBase64: encodedFaceImage, // only include if required
  })
}
catch (err) {
  // Handle errors
}
  • Identity documents must be issued by a government agency.

  • The document type can be one of driverLicense, passport or idCard.

  • The country value must be an ISO 3166-1 alpha-2 code returned from the listSupportedCountries() API.

  • Images of identification documents should be taken against a dark background, in a well-lit room and fill the majority of the image, with only a small border of the background surface showing.

  • All four corners of the identification document must be visible in the image.

  • Prior to Base64 encoding, the images should be in PNG, JPG or GIF format, and not exceed 5 MB in size each.

  • When submitting a passport for verification, use the photo page image for both the front and back images.

  • The face image parameter must only be included if required, based on the result of the isFaceImageRequiredWithDocumentVerification API described above.

Once submitted the document verification process can be immediate or may take some time. The status of the document verification process is returned in the documentVerificationStatus property of the result. The documentVerificationStatus property of the returned VerifiedIdentity can have the following values:

documentVerificationStatus value
Meaning

notRequired

Required verification method does not require submission of an ID document

notAttempted

Required verification method requires submission of an ID document but ID document submission has not yet been performed.

pending

Document verification could not be completed synchronously and status will need to be periodically checked. To check, call the checkIdentityVerification method.

documentUnreadable

The submitted document images could not be processed because they do not meet one or more of the criteria documented above.

succeeded

The submitted document images were able to be used to successfully verify the user's identity. This is a final state.

failed

The submitted document images were not able to be used to successfully verify the user's identity. This is a final state.

Once the user's identity has been verified successfully the verification status is persisted on the user record and the user is not required to verify their identity again.

Determine if a Face Image is Required with ID Document Capture

To check if a face image must be provided along with ID document at the time of document capture (see captureAndVerifyIdentityDocument method described below):

do {
    let faceImageRequired = try await identityVerificationClient.isFaceImageRequiredWithDocumentCapture(option: .remoteOnly)
} catch {
    // Handle error. An error may be thrown if the backend is unable to perform
    // requested operation due to availability or security issues.
    // An error might be also be thrown for unrecoverable circumstances arising
    // from programmatic error or configuration error. For example, if the keychain
    // access entitlement is not set up correctly or basic system resources are
    // unavailable.
}
CoroutineScope(Dispatchers.IO).launch {
    try {
        val faceImageRequired = identityVerificationClient.isFaceImageRequiredWithDocumentCapture()
    } catch (e: SudoIdentityVerificationException) {
        // Handle errors.
    }
}
try {
  const faceImageRequired = await identityVerificationClient.isFaceImageRequiredWithDocumentCapture()
}
catch (err) {
  // Handle errors
}

The isFaceImageRequired() API returns a boolean value.

Capture and Verify Identity Document

Upload ID Document Images via API

Use this API to initiate an on-boarding process. ID document images are provided to this API, which attempts to extract the identity information from the images of government issued ID documents, and then verify the identity using the extracted information.

Unlike the verifyIdentityDocument() API described above, verifyIdentity() API does not need to be called before calling the captureAndVerifyIdentityDocument() API.

do {
    let verifiedIdentity = try await identityVerificationClient.captureAndVerifyIdentityDocument(
        input: VerifyIdentityDocument(
            image: frontImage, 
            backImage: backImage,
            faceImage: faceImage, // only include if required
            country: country,
            documentType: .driverLicense
        )
    )
    if verifiedIdentity.verified {
        // Identity verified succcessfully.
    } else {
        // Identity could not be verified.
    }
} catch {
    // Handle error.
}
val input = VerifyIdentityDocumentInput(
    documentType = IdDocumentType.driverLicense,
    country = "US",
    imageBase64 = encodedDocumentFrontImage,
    backImageBase64 = encodedDocumentBackImage
    faceImageBase64: encodedFaceImage, // only include if required
)
launch {
    try {
        val verifiedIdentity = withContext(Dispatchers.IO) {
            identityVerificationClient.captureAndVerifyIdentityDocument(
                input
            ) 
        }
        // The returned [verifiedIdentity] result has been verified.
    } catch (e: SudoIdentityVerificationException) {
        // Handle errors.
    }
}
try {
  const verifiedIdentity = await identityVerificationClient.captureAndVerifyIdentityDocument({
    documentType: IdDocumentType.driverLicense,
    country: 'US',
    imageBase64: encodedDocumentFrontImage,
    backImageBase64: encodedDocumentBackImage,
    faceImageBase64: encodedFaceImage, // only include if required
  })
}
catch (err) {
  // Handle errors
}
  • Identity documents must be issued by a government agency.

  • The document type can be one of driverLicense or idCard. Passport images cannot be used as they do not provide a mechanism to verify address.

  • The country value must be an ISO 3166-1 alpha-2 code returned from the listSupportedCountries() API.

  • Images of identification documents should be taken against a dark background, in a well-lit room and fill the majority of the image, with only a small border of the background surface showing.

  • All four corners of the identification document must be visible in the image.

  • Prior to Base64 encoding, the images should be in PNG, JPG or GIF format, and not exceed 5 MB in size each.

  • The face image parameter must only be included if required, based on the result of the isFaceImageRequiredWithDocumentCapture API described above.

Upload ID Document Images via Web Browser

Use this API to initiate an on-boarding process where ID document images are uploaded via a web browser.

do {
    let idDocumentCaptureInitiationInfo = try await identityVerificationClient.initiateIdentityDocumentCapture()
    // browse to idDocumentCaptureInitiationInfo.documentCaptureUrl
} catch {
    // Handle error.
}
launch {
    try {
        val idDocumentCaptureInitiationInfo = withContext(Dispatchers.IO) {
            identityVerificationClient.initiateIdentityDocumentCapture() 
        }
        // browse to idDocumentCaptureInitiationInfo.documentCaptureUrl
    } catch (e: SudoIdentityVerificationException) {
        // Handle errors.
    }
}
try {
  const idDocumentCaptureInitiationInfo = await identityVerificationClient.initiateIdentityDocumentCapture()
  // browse to idDocumentCaptureInitiationInfo.documentCaptureUrl 
}
catch (err) {
  // Handle errors
}
  • Identity documents must be issued by a government agency.

  • Once obtained in a successful response to this API, the value of the documentCaptureUrl can be used to direct the end user to the web site where they can upload their ID document. The expiry time for the URL is also provided.

  • The web site will guide the end user and preprocess ID document images to ensure they meet the provider requirements including brightness, contrast, glare and cropping.

  • If facial comparison is configured in the environment, the web site will also guide the end user to capture a facial image.

  • After completing the upload, the client application should call the API to Check Secure ID Verification Status to retrieve the result of the ID document capture and verification.

PreviousList Supported CountriesNextCheck Secure ID Verification Status

Last updated 28 days ago

🗺️