NAV Navbar
Python NodeJS GraphQL

Introduction

The Vouched Verification SDK is a set of tools that you can use to submit, access and manage verification jobs. You can access Vouched Verification with our client libraries in a wide variety of popular programming languages.

Recognized IDs

Browser Client

Getting Started

Initialize the Vouched client


<script src="https://static.vouched.id/widget/vouched.js"></script>
<script type='text/javascript'>
(function(){
    var vouched = Vouched({
        // your public key
        appId: '<APP_ID>',
        types: ['id-verification'],
        content: {
          // successful submission
          success: 'success',
          // the user disputes the results
          review:
            'Thank you for updating your information. We will review and get back to you.',
          // verification passed
          verifyPass:
            'Everything looks good to us. Verify your information and click next.',
          // verification failed
          verifyFail:
            "We couldn't verify you. If you disagree, update your information and click next."
        },
        /////////////////////////
        // optional verification step
        verification: {
          firstName: 'John',
          lastName: 'Bao',
          birthDate: '09/11/1978'
        },

        // needed if theres a customer service claim when
        // the user disagree with the results
        callbackURL: 'https://www.google.com',
        theme: {
          baseColor: '#FD814B',
          bgColor: '#000'
        },
        onSubmit: ({ stage, attempts }) => {
          console.log('submit', { stage, attempts });
        },
        onInit: () => {
          console.log('initialization');
        },
        onDone: (job)=> {
            // notify a server process that a job is complete
            // query the job with the token
            fetch(`/api/idv?job_token=${job.token}`);
        }
    })
    vouched.mount('#vouched-element')
})();
</script>
<body>
    <div id='vouched-element' style="height: 100%"/>
</body>

SDK Client API

Getting Started


Obtain the Client version, currently (0.0.5b9)
Obtain the version number and FURY_AUTH token.

Update `requirements.txt` for:

--index-url https://${FURY_AUTH}@pypi.fury.io/woollylabs/
--extra-index-url https://pypi.org/simple/ private-package=0.0.1

vouched-client==<CLIENT_VERSION>

Install with pip:

FURY_AUTH=<FURY_AUTH_TOKEN> pip install --no-cache-dir -r ./requirements.txt

Some OSes does not allow the reading of environment variables in `requirements.txt`.
In this case, replace `${FURY_AUTH}` in `requirements.txt` with the actual token.

The header parameter `X-Api-Key` is required for all
GraphQL requests.

headers['X-Api-Key']=<secret_app_key>


lipvips is used to compress images. Installation instructions
for libvips found at https://github.com/lovell/sharp-libvips.

Obtain the Client version, currently (0.0.1-beta.9)

Update `package.json` for:

{
  "dependencies": {
    "@vouched/client": "<CLIENT_VERSION>"
  }
}

Append the following to the project's `.npmrc`,
for details refer to https://docs.npmjs.com/files/npmrc:

@vouched:registry=https://npm.fury.io/woollylabs/
//npm.fury.io/woollylabs/:_authToken=${FURY_AUTH}

Run:
FURY_AUTH=<FURY_AUTH_TOKEN> npm install

Some OSes does not allow the reading of environment variables in `.npmrc`.
In this case, replace `${FURY_AUTH}` in `.npmrc` with the actual token.

Create the Vouched client

const Client = require('@vouched/client').default;

const client = Client(secret_app_key);
from vouched.api import Client

client = Client(secret_app_key)

Arguments

Parameter Type Required Description
key String * Secret Application Key

Returns

Parameter Type Required Description
client Client * Vouched client

Errors:

Update client key

secret_client_key = <SECRET>
data = client.update_secret_client_key(secret_client_key=secret_client_key)

const secretClientKey = <SECRET>
const data = client.updateSecretClientKey(secretClientKey);

  mutation updateSecretClientKey($secretClientKey: String) {
    updateSecretClientKey(secretClientKey: $secretClientKey) {
      secretClientKey
    }
  }

Arguments

Parameter Type Required Description
secretClientKey String The secret key to be included in the header X-Api-Key of the webhook call.

Returns

Parameter Type Required Description
secretClientKey String The updated secretClientKey

Errors:

Submit a verification job


from vouched.utils import image_to_base64

user_photo_base64 = image_to_base64('/opt/app/tests/data/selfie.png')
id_photo_base64 = image_to_base64('/opt/app/tests/data/id.jpg')
job = client.submit(
    user_photo=user_photo_base64,
    id_photo=id_photo_base64,
    type='id-verification',
    first_name='Janice',
    dob='06/22/1990',
    last_name='Way'
)


const utils = require('@vouched/client').utils;

const userPhotoBase64 = await utils.imageToBase64(
    '/opt/app/tests/data/selfie.png'
);
const idPhotoBase64 = await utils.imageToBase64(
    '/opt/app/tests/data/id.jpg'
);
const job = await client.submit({
    userPhoto:userPhotoBase64,
    idPhoto:idPhotoBase64,
    type:'id-verification',
    firstName:'Janice',
    dob:'06/22/1990',
    lastName:'Way'
})

  fragment Job on Job {
    id
    status
    request {
      type
      callbackURL
      parameters {
        idPhoto
        userPhoto
        twicPhoto
        carInsurancePhoto
        dotPhoto
        firstName
        lastName
        dob
      }
    }
    result {
      success
      type
      country
      state
      id
      firstName
      lastName
      expireDate
      birthDate
      confidences {
        id
        backId
        selfie
        idMatch
        faceMatch
      }
    }
    errors {
      type
      message
      suggestion
    }
    submitted
  }
  input JobParams {
    userPhoto: String
    idPhoto: String
    twicPhoto: String
    carInsurancePhoto: String
    dotPhoto: String
    id: String
    firstName: String
    lastName: String
    dob: String
  }
  mutation submitJob(
    $type: String!
    $callbackURL: String
    $params: JobParams
  ) {
    submitJob(
      type: $type
      callbackURL: $callbackURL
      params: $params
    ) {
      ...Job
    }
  }

Arguments

Parameter Type Required Description
type String * Type of AI job ("id-verification")
callbackURL String Upon the job's completion, Vouched will POST the job results to the webhook. If the callbackURL is not given, Vouch will process the job in realtime.
parameters Object * Object for 'id-verification'.
Property Type Required Description
userPhoto String, Buffer   The user's id comparison photo. Supported types include image/png, image/jpeg
idPhoto String, Buffer * The user's official identification photo. Supported types include image/png, image/jpeg
idPhotoBack String, Buffer   The user's official back of the identification photo. Supported types include image/png, image/jpeg \*\*\* TODO Python addition
firstName String   The user's first name.
dob String   Date in the format MM/DD/YYYY.
lastName String   The user's last name.

Returns

Parameter Type Required Description
job Job * The newly created job.

Errors:

Remove a job


job = client.remove_job(
    id='USkjk33'
)


const job = await client.remove({ id: 'ofm1k9xF' })


  fragment Job on Job {
    .... Refer to submitJob
  }
  mutation removeJob(
  $id: ID!
  ) {
    removeJob(
      id: $id
    ) {
      ...Job
    }
  }


Arguments

Parameter Type Required Description
id String * ID of the job to remove

Returns

Parameter Type Required Description
job Job * The removed job.

Errors:

Provide results on jobs

jobs = client.jobs(
    page=1,
    page_size=2,
    type='id-verification',
    token=<TOKEN_FROM_WEB_CLIENT>,
    status='active',
    sort_by='date',
    sort_order='desc',
    with_photos=True,
    from_date='2017-01-24T04:44:00+00:00',
    to_date='2020-12-24T04:44:00+00:00'
 )

  query jobs(
    $id: ID
    $token: String
    $ids: [ID]
    $type: String
    $status: String
    $to: String
    $from: String
    $withPhotos: Boolean
    $sortOrder: String
    $sortBy: String
    $page: Int
    $pageSize: Int
  ) {
    jobs(
      withPhotos: $withPhotos
      id: $id
      ids: $ids
      status: $status
      token: $token
      type: $type
      to: $to
      from: $from
      sortOrder: $sortOrder
      sortBy: $sortBy
      page: $page
      pageSize: $pageSize
    ) {
      total
      totalPages
      pageSize
      page
      items {
        ...Job
      }
    }
  }
const jobs = client.jobs({
    page:1,
    pageSize:2,
    type:'id-verification',
    status:'active',
    token:<TOKEN_FROM_WEB_CLIENT>,
    sortBy:'date',
    sortOrder:'desc',
    withPhotos:true,
    fromDate:'2017-01-24T04:44:00+00:00',
    toDate:'2020-12-24T04:44:00+00:00'
})


Arguments:

Parameter Type Required Description
id ID Filter by job ID.
type String Type of job ("id-verification")
ids [ID] Filter by a list of job IDs.
page Int Paginate list by page where the page starts at 1, defaults to 1.
pageSize Int The number of items for a page, max 1000, defaults to 100
sortBy String Sort the list from ("date", "status").
sortOrder String Order the sort from ("asc", "desc").
status String Filter by status from ("active","completed")
to String Filter by submitted to ISO8601 date.
from String Filter by submitted from ISO8601 date.
withPhotos Boolean Defaults to False. The returned job will contain detailed information idPhoto, idPhotoBack, and userPhoto.

Returns

Parameter Type Required Description
jobs [Job] * List of paginated jobs without detailed information idPhoto and userPhoto.
totalPages Int * Total number of pages of jobs.
pageSize Int * The requested page size.
page Int * The requested page.
total Int * Total number of filtered jobs.

Errors:

Types

Error

Property Type Required Description
type String *
  • InvalidRequestError - The request is invalid.
  • FaceMatchError - Face match felled below the threshold
  • NameMatchError - Name match felled below the threshold
  • BirthDateMatchError - Birth date match felled below the threshold
  • InvalidIdPhotoError - The ID is invalid
  • InvalidUserPhotoError - The user photo (selfie) is invalid
  • UNAUTHENTICATED/AuthenticationError - The request could not be authenticated
  • ConnectionError - A connection error occurred while communicating to the Vouched service
  • InvalidIdBackPhotoError - The back of the ID is invalid
  • UnknownSystemError - A unknown system error occurred
  • InvalidIdError - The ID is invalid
message String * Details on the occurring error.
suggestion String A suggestion for matching name, John Smith, Jon Smith.
errors [Error] InvalidRequestError contains a sub list of errors

Job

Property Type Required Description
id ID * Job ID
status String * Job status from ("active","completed")
submitted String * ISO8601 date
request Object * Object for 'id-verification'.
Property Type Required Description
type String * Job type
callbackURL String POST enabled webhook
parameters JobParameters * Object for 'id-verification'
result Object * Object For 'id-verification'
Property Type Required Description
success Boolean * Did the id verification completed successfully?
type String The id type
state String The issuing state of the id if applicable
country String The issuing country of the id
id String The verified id number of the id
expireDate String The verified expired date in the format MM/DD/YYYY.
birthDate String The verified date in the format MM/DD/YYYY.
firstName String The user's verified first name.
lastName String The user's verified last name.
confidences Confidences Confidence scores
errors [Error] List of errors for unsuccessful completed jobs.

Confidences

Property Type Required Description
id Float * Confidence score for an id photo, 0-1.0
backId Float * Confidence score for the back of the id photo, 0-1.0
selfie Float * Confidence score for a selfie photo, 0-1.0
idMatch Float * Confidence score for matching data on the id, 0-1.0
faceMatch Float * Confidence score for matching faces, 0-1.0

JobParameters

Property Type Required Description
idPhoto String * The user's official identification photo in base64.
userPhoto String The user's id comparison photo in base64.
twicPhoto String The user's id twic id photo in base64.
carInsurancePhoto String The user's id car insurance photo in base64.
dotPhoto String The user's id dot letter photo in base64.
idPhotoBack String The user's official back of the identification photo in base64. *** TODO Python addition
dob String Date in the format MM/DD/YYYY.
firstName String The user's first name.
lastName String The user's last name.