Skip to main content

Create, Update or Link Accounts

An account is a unique identifier (UUID) that is used to associate a set of credentials and transactions (i.e. workflow executions) with a customer. Each transaction is associated with one account, and an account can be associated with multiple transactions.

  • If you are onboarding a new customer, use the POST request to create a new account.
  • If you are updating an existing account, use the PUT request, with the account ID value as a path parameter.
important

For the complete API specification see: Account API Reference.

note

Creating or updating the account is always done through a REST API call, regardless of the integration channel. Account requests are subject to Rate Limits.

Account Request​

The request body for either an account creation or account update request is a JSON object.

Required Fields​

FieldTypeMax. LengthNotes
customerInternalReferencestring100Customer internal reference for a request to link it in the customer backend (must not contain any PII). Must not contain any of the following characters: <>"/;`%
workflowDefinitionobject255A key value is required to specify the workflow for the transaction. Other values may be required, depending on the workflow.

Account Request Body Required Fields Example​

{
  "customerInternalReference": "myTransactionReference",
  "workflowDefinition": {
    "key": 10164
  }
}

Optional Fields​

FieldTypeMax. LengthNotes
userReferencestring100Reference for the end user in the customer backend (must not contain any PII)
reportingCriteriastring255Additional information provided by a customer for searching and aggregation purposes
callbackUrlstring255Definition of the callback URL for this particular request. Overrides callback URL in the Jumio Portal.
tokenLifetimestringmin: 5m, max: 60d, default: 30mShould be a valid date period unit definition: s - seconds, m - minutes, h - hours d - days. Example: ‘1d’ / ‘30m’ / ‘600s’. Overrides Authorization token lifetime in the Jumio Portal.
webobjectUsed to override default values that are configured in the Portal. Only relevant for the WEB channel.
userConsentobjectIf your integration uses REST APIs for Credential Acquisition you must obtain the end-user's consent to share their personal information with Jumio. See: End-User Consent to Collect Personal Data.
overrideSettingsobjectUsed to override some tenant settings.

workflowDefinition​

A workflowDefinition object is required for all requests, and must include a key value that specifies the workflow for the transaction.

Additional objects may be required to configure workflows that use some services or risk signals, including:

  • Credentials object used to specify a particular type of credential to upload for the transaction. For example, the Document Verification service (standalone workflow 10026), or any workflow that uses the extraction capability to extract data from a document credential.
  • Capabilities object used to specify configuration options for specific capabilities.

credentials​

An array of the credentials required for the workflow. A credentials array is required if credentials are going to be uploaded by REST API calls. A credentials array is also used to:

credentials Object Example (ID)​
  • Limit the sets of ID types and countries that are presented to end user during the customer journey. For example, the following limits the end user to choosing either USA or Canada, and either Driving License or ID Card. No other options are presented.
"credentials": [
    {
        "category": "ID",
        "country": {
                "predefinedType": "DEFINED",
                "values": ["USA", "CAN", "BRA"]
        },
        "type": {
            "predefinedType": "DEFINED",
            "values": ["DRIVING_LICENSE", "ID_CARD"]
        },
        "subType": {
            "predefinedType":"DEFINED",
            "values":["DIGITAL_DRIVING_LICENSE_PDF"]
        }
    }
]
info
  • subType only supports the value DIGITAL_DRIVING_LICENSE_PDF. This is available only for Web integration and requires country: "BRA" with type: "DRIVING_LICENSE".
  • In the Web Client, if exactly one country + document type combination is preconfigured in the credentials array, the document-type selection screen will be skipped, and the user will proceed directly to uploading that document.
  • If multiple country and/or document type options are preconfigured, then the Web Client will show a limited selection screen, displaying only those predefined countries and document types to the end user.
  • Limitation: Because of current constraints in the Web Client, only the first specified country and type pair may be enforced when subType is used.
credentials Object Example (Document)​
  • Specify a document credential to use with a Document Verification workflow such as 10026. In this case the type and country must be specified to enable the extraction capability. For example, the following is required to enable the extraction of expected values from a Bank Statement from the USA:
"credentials": [
            {
                "category": "DOCUMENT",
                "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA"]
                },
                "type": {
                    "predefinedType": "DEFINED",
                    "values": ["BS"]
                }  
            }
        ]
credentials Object Example (FACEMAP)​

Specify a FACEMAP credential to use with an Authentication workflow such as 10011. In this case, the category must be set to "FACEMAP" and a type must be specified to determine the FACEMAP source. Possible values for the FACEMAP type include:

  • JUMIO_STANDARD
  • JUMIO_PREMIUM

For example, the following configuration is required to enable the use of Jumio Standard FACEMAP:

    "credentials" : [{
        "category" : "FACEMAP",
        "type" : {
            "values" : ["JUMIO_STANDARD"]
        }
    }]
FieldTypeNotes
idstringUUID of the credentials
categorystringCredential category. Possible values:
  • ID
  • DOCUMENT
  • FACEMAP
It is not common to specify a FACEMAP. Consult with your account representative for additional information.
countryobjectDefined at least one ISO 3166-1 alpha-3 country code for the workflow definition. Possible values: ISO 3166-1 alpha-3 country code
typeobjectDefined number of credential type codes. Possible values:
  • ID_CARD
  • DRIVING LICENSE
  • PASSPORT
  • VISA
subTypeobjectThe subType field supports only one value: DIGITAL_DRIVING_LICENSE_PDF. This option is available only for Web integrations and requires country: "BRA" and type: "DRIVING_LICENSE".

capabilities​

Provide values for capabilities that require additional configuration properties.

FieldTypeNotes
watchlistScreeningobjectOverride the default search profile.
documentVerificationobjectConfigure additional capabilities to use with Document Verification.
ekycCheckobjectUsed to specify a 1+1 or 2+2 search.
workflowDecisionobjectUsed to specify a ruleset to use instead of the default ruleset configured for the tenant.
rulesetobjectOverride the default ruleset used by the workflow.
watchlistScreening​

Used to configure the Watchlist Screening capability by overriding the default searchProfile. Consult your Jumio representative for additional information.

     "capabilities":{
        "watchlistScreening": {
        }
     }
info

searchProfile is the alphanumeric string that is the identifier for your searchProfile.

documentVerification​

Used to disable Extraction in cases where a Document is uploaded to be stored but extracting the data is not required. Consult your Jumio representative for additional information.

     "capabilities": {
         "documentVerification": {
             "enableExtraction": "false"
         }
     }
ekycCheck​

Includes a searchType value. Allowed values are:

  • one if requesting a 1+1 check
  • two if requesting a 2+x2 check
     "capabilities": {
       "ekycCheck": {
         "searchType": "one"
       }
     }
workflowDecision​

Used to specify a ruleset to use instead of the default ruleset configured for the tenant.

     "capabilities": {
       "workflowDecision": {
         "riskScoreRulesetId": "81c616b7-d47e-4cb2-8c4f-17267f2106f3"
       }
     }
ruleset to work with default scoring (deprecated)​
info

Sending rules using the workflowDecision object is preferred over using a ruleset for most cases. This flow is only to handle exceptions.

Used to specify one or more rulesets to use instead of the default ruleset(s) used by the workflow.

     "capabilities": {
         "ruleset": {
             "ids": ["id1", "id2", "id3"]
         }
     }

The values in the "ids" array are the ruleset IDs of the rulesets you want to use. See also: Working with Rules.

web​

These values are only relevant for the WEB channel. They are used to override the default values that are configured in the Portal. See Application Settings.

FieldTypeMax. LengthNotes
successUrlstring1900URL to which the browser will send the end user at the end of a successful web acquisition user journey. Overrides default success URL.*
errorUrlstring1900URL to which the browser will send the end user at the end of a failed web acquisition user journey. Overrides default error URL.*
localestring5Renders content in the specified language. Overrides Default locale.
note

Success and error URLs provided through an Account request are less restrictive than the defaults. For example, local domains and schemes for deep linking are supported.

web Object Example​
"web":{
 "successUrl":"https://www.yourcompany.com/success",
 "errorUrl":"https://www.yourcompany.com/error",
 "locale":"es"
}

userConsent​

Checkout End-User Consent to Collect Biometric Data for details.

"userConsent": {
 "userIp": "226.80.211.232",
 "userLocation": {
   "country": "USA",
   "state": "IL"
 },
 "consent": {
   "obtained": "yes",
   "obtainedAt": "2022-07-20T17:20:35.000Z"
 }
}

overrideSettings​

You can override some tenant settings for a transaction.

FieldTypeNotes
crossDeviceOnlybooleanSpecifies whether credential acquisition must be done on a mobile device.
crossDeviceOptionstringSpecifies how a mobile device can get the connection:
  • DEFAULT – End user can choose email or QR Code
  • QR_ONLY – Only the QR Code option will be shown
  • EMAIL_ONLY – Only the email option will be shown

overrideSettings Object Example​

{
 "customerInternalReference":"myCompany",
 "overrideSettings":{
     "crossDeviceOnly": true,
     "crossDeviceOption":"QR_ONLY"
 },
 "workflowDefinition":{
     ...
 }
}

Account Responses​

The response from the API includes the UUID and additional information you will need for the transaction, including:

  • The account ID and the workflow execution ID for the transaction. These values are used for viewing or retrieving Workflow Transactions.
  • The fully parameterized URL for the Web Client.
  • The authorization token you will need if you are using one of the Mobile SDKs.
  • Details about the credentials that need to be provided for evaluation by the workflow. This includes data that will be used by the integration channel to upload the credential and associate it with the account.
    tip

    Workflows that evaluate multiple instances of the same type of credential can provide a "label" value to distinguish between the instances.

  • The URLs you will use if you are Uploading Credentials using the REST APIs.
Example Account Response
{
 "timestamp": "2022-11-28T23:45:02.536Z",
 "account": {
     "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
 },
 "web": {
     "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ&locale=en-US"
 },
 "sdk": {
     "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
 },
 "workflowExecution": {
     "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
     "credentials": [
         {
             "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
             "category": "ID",
             "allowedChannels": [
                 "WEB",
                 "API",
                 "SDK"
             ],
             "api": {
                 "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                 "parts": {
                     "front": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT",
                     "back": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
                 },
                 "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
             }
         },
         {
             "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
             "category": "FACEMAP",
             "allowedChannels": [
                 "WEB",
                 "SDK"
             ]
         },
         {
             "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
             "category": "SELFIE",
             "allowedChannels": [
                 "WEB",
                 "API",
                 "SDK"
             ],
             "api": {
                 "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                 "parts": {
                     "face": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
                 },
                 "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
             }
         }
     ]
 }
}
note

For ID and Selfie credentials upload JPEG or PNG files with a maximum size of 15 MB and the following image resolution limits:

Image TypeResolution (min)Resolution (max)Additional Requirements
Document Image563x355 px8000x8000 pxThe document must be at least 512 px wide and 323 px high.
Selfie Image480x640 px8000x8000 pxThe face must be at least 320 px tall and cover at least 15% of the image.

Table of Contents