Credential Reference

The documents, scanned images, or prepared data that are evaluated by a Jumio workflow are called credentials. Each Jumio capability specifies the credential(s) it can evaluate. The required credentials for each capability that is invoked by a workflow must be uploaded to the end-user accountClosed prior to initiating the workflow.

The following topics describe the types of credentials that are currently supported:

• ID
• Selfie
• Facemap
• Document
• Prepared Data

ID

ID is a government-issued identification document such as a passport, identification card, or a driver's license.

The list of ID types that your integration supports, as well as a list of the IDs that Jumio supports is available from the Jumio Portal by logging in as an Administrator and going to Settings > Identity Verification > Accepted IDs and Settings > Identity Verification > Supported IDs. For additional information see Accepted IDs and Supported IDs.

Depending on the type of ID either just a FRONT image or both FRONT and BACK images may be required. If your integration uses the Web Client or the mobile SDKs the customer journeyClosed will guide the end user to provide the required parts.

Selfie

Selfie is an image of the end user. It is uploaded and stored as a single FACE part. If your integration uses the Web Client or the mobile SDKs the customer journeyClosed will guide the end user to provide the Selfie. Your integration can also upload an image using the API.

FACEMAP

FACEMAP is a unique credential that is made up of several images of the end user taken in rapid succession. Unlike other types of credentials a FACEMAP cannot be uploaded directly through the API. If your integration uses the Jumio Web Client or SDKs with a workflow that evaluates a FACEMAP, the FACEMAP will be created and uploaded along with the SELFIE as the end user completes the customer journeyClosed.

The FACEMAP is evaluated by the Liveness capability to ensure that the end user who is completing the customer journey is a living person.

ℹ️   If for any reason the FACEMAP cannot be created, the Liveness capability will evaluate the SELFIE instead.

While you cannot upload a FACEMAP through the APIs you can access and download the images that comprise the FACEMAP from the retrieval APIs. See Workflow Credentials.

ℹ️   The Authentication On-Premises service supports downloading and uploading a binary version of a Facemap. Using it requires additional configuration for your tenant. The binary format is not supported for other uses.

Document

Images or PDF copies of documents such as bank statements, utility bills, or insurance cards can be used to identity an end user. Workflows that accept a DOCUMENT credential pass it to the Extraction capability. A successful extraction requires at least one of the following values:

• Name
• Issue Date
• Address

Work with your Jumio Account Representative to identify and configure the DOCUMENT types you intend to support, and the fields you expect to be extracted.

Uploads are restricted to JPEG, PNG or PDF file types totaling 15MB in size. Credit card uploads are limited to 2 images or PDF pages, and all other document types are limited to 30 images or PDF pages.

Specifying the DOCUMENT in the Account Request

When using a workflow that requires a DOCUMENT credential, the request body to the Account API (see Creating or Updating Accounts) must include a credential node with DOCUMENT as the category value. It must have also include country and type fields, each with exactly one value in it. If any of these conditions are not met, the request will result in validation errors.

For example, to request the standalone DocV workflow (10026) with a bank statement (code: BS):

{
    "customerInternalReference":"postman-tomg-call2",
    "callbackUrl":"https://enxduej0n1fgwkv.m.pipedream.net",
    "workflowDefinition":{
        "key": 10026,
        "credentials": [
            {
                "category": "DOCUMENT",
                "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA"]
                },
                "type": {
                    "predefinedType": "DEFINED",
                    "values": ["BS"]
                }  
            }
        ]
    },
    "userReference": "postman-tomg",
    "tokenLifetime": "10m"
}

Supported Documents

These document types are supported for upload and data extraction. Other document types may be available, and custom documents may be added. Consult your Jumio SE for details about specific document types.

• BC (Birth certificate)
• BS (Bank statement)
• CAAP (Cash advance application)
• CB (Council bill)
• CC (Credit card)
• CCS (Credit card statement)
• CRC (Corporate resolution certificate)
• HCC (Health care card)
• IC (Insurance card)
• LAG (Lease agreement)
• LOAP (Loan application)
• MEDC (Medicare card)
• MOAP (Mortgage application)
• PB (Phone bill)
• SEL (School enrolment letter)
• SENC (Seniors card)
• SS (Superannuation statement)
• SSC (Social security card)
• STUC (Student card)
• TAC (Trade association card)
• TR (Tax return)
• UB (Utility bill)
• VC (Voided check)
• VT (Vehicle title)
• WWCC (Working with children check)

ℹ️   Custom codes you have added must be unique, and must not be the reserved keywords CUSTOM or OTHER.

Prepared data

Prepared data is used to upload values for data fields that are required by a capability or risk signal in a workflow, but are not extracted from another credential such as an ID or Document. For example, many Risk Signals may be called using standalone workflows that do not include other capabilities such as Extraction, and do not require any other credentials. In these cases, the data required by the risk signal is first uploaded as prepared data, using the REST API. Using prepared data is only supported by the REST APIs for Credential Acquisition integration channel.

When your API request to create or update an account specifies a workflow that supports uploading prepared data the response body will include a credential object with a category value of DATA and a api.parts.prepared_data URL to the parametrized endpoint for uploading the data. The object also includes the api.token value for authorizing the upload request.

"credentials": [
         ...
         {
            "id": "be032ae5-07ea-417b-b7e5-9ef6c3e68132",
            "category": "DATA",
            "label": "DATA",
            "allowedChannels": [
               "API"
            ],
            "api": {
               "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOQ4CMQxA0bukxlI2JzYdoqLlBomXboACCRDi7gxzA9qv99_Bnod72IfUIyOXxrn1EnZhiJx07T5NFZWgmHaoiAgzJQes0-NI3hTtxzdcErWRWgeVLFALKUxhAuvMRHlibLzih9s_XM7mq15ex-tyG5fXL21_F1KJ7FATGtTcHZh8giUfGHXOnGP4fAHVKVVI4wAAAA.IADgEkiZhlQkGbG3N-u-FNO7ECPzS2dJ9qLkOJG7WMaTDGemnWsk57iGZugFN-0VrT2U9L0m3UzqscTPJw__Yw",
               "parts": {
                  "prepared_data": "https://api.amer-1.jumio.ai/api/v1/accounts/fbedd5d8-3ed7-4555-b11f-54bf0a1f6d5e/workflow-executions/3186a167-dc2c-438d-bc98-e799882b5069/credentials/be032ae5-07ea-417b-b7e5-9ef6c3e68132/parts/PREPARED_DATA"
               },
               "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/fbedd5d8-3ed7-4555-b11f-54bf0a1f6d5e/workflow-executions/3186a167-dc2c-438d-bc98-e799882b5069"
            }
         }
         ...

See also:

• Creating or Updating Accounts
• Prepared Data API Reference

ℹ️   Depending on the workflow, uploading prepared data may be either optional or mandatory. Also, specific fields and values may be either optional or mandatory.

Example Prepared Data Upload Request Body

Prepared data is uploaded by making a POST request to the prepared_data URL from the account response. The request uses Bearer Token authentication with the token from the account response.

The body of the request is a JSON object with the desired or required values. For example:

{
    "firstName": "John",
    "middleName": "",
    "lastName": "Smith",
    "dateOfBirth": "1972-11-16",
    "socialSecurityNumber": "123456789",
    "email": "email@gmail.com",
    "phoneNumber": "+15031234567",
    "personalNumber": "",
    "address": {
        "line1": "12345 SW Address Ln",
        "postalCode": "97201",
        "city": "Portland",
        "subdivision": "OR",
        "country": "USA"
    },
    "id": {
        "idNumber": "057033812",
        "type": "DRIVING_LICENSE",
        "issuingDate": "2021-01-22",
        "expiryDate": "2026-01-22"
    }
}

ℹ️   To prevent SQL/XML injection threats the character set [^<>"/;`%{}|] is not allowed in the prepared data body values for these keys: firstName, lastName, middleName, paternalSurname , maternalSurname ,email, phoneNumber.

Supported Fields

ℹ️   Not all values are required for all requests. See the documentation for specific risk signals for details on required values and formats.

Field	Type	Example	Description
suffix	string	Mr, Mrs, Ms
firstName	string	John	First name of the subject.
middleName	string	Percival	Middle name of the subject.
lastName	string	Smith	Last name of the subject.
sex	string	M	Gender of Id subject. M for male and F for female.
dateOfBirth	string($date)	1972-11-16	Date of birth in ISO 8601 date format.
socialSecurityNumber	string	123456789	USA SSN of the subject.
nationality	string	USA	Nationality of the subject.
email	string($email)	john.smith@mymail.com	Primary email address of the subject.
phoneNumber	string	+2134445678	Primary phone number of the subject in E.164 format.
phoneNumber2	string	+3109992939	Alternate phone number of the subject in E.164 format.
personalNumber	string		For Brazil, this will be the CPF number.
address	Object		Primary address for the subject.
address.line1	string	12345 SW Address Ln
address.line2	string	Suite 707
address.city	string	Portland	City of residence as it appears on the Id.
address.postalCode	string	97201	Postal or zip code.
address.subdivision	string	OR	City subdivision of residence as it appears on the Id.
address.country	string	USA	Country in ISO-3166-1 Alpha-3 Code or ISO-3166-1 Alpha-2 Code format.
id	Object		Document data.
id.idNumber	string	057033812	Primary id number on the identity document.
id.Type	string	DRIVING_LICENSE	Type of identity document.
id.subType	string		Sub-type of identity document.
id.issuingDate	string	2021-01-22	Date the document was issued.
id.expiryDate	string	2026-01-22	Date the document will expire.