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

passports
- AU, BR, BY, CA, CN, CO, DE, DK, FR, GB, GH, HN, ID, IE, IN, IT, JM, JP, KR, MX, MY, NG, NZ, PE, PH, PL, SG, TH, US, VN
identification cards - US, VN
driver's license - US, GB, CA, BY
commercial driver's license - US, GB, CA
driving permits - US, GB, CA

Browser Client

Getting Started

Obtain the application id

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 FURY_AUTH token
Obtain the secret app key


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:

InvalidRequestError

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:

AuthenticationError
ConnectionError
InvalidRequestError
UnknownSystemError

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:

AuthenticationError
ConnectionError
InvalidRequestError
UnknownSystemError

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:

AuthenticationError
ConnectionError
InvalidRequestError
UnknownSystemError

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	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:

AuthenticationError
ConnectionError
InvalidRequestError
UnknownSystemError

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

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.