Skip to main content

Quickstart Guide: Standalone Risk Signal

In many workflows, you may need to provide or enhance the data. This typically includes information to activate risk signals (such as phone or email) and may also involve your custom, shared data inputs.

Prerequisites​

To retrieve your Credentials, log in to the portal and obtain your client ID and client secret. These are required to authenticate the /token endpoint.

Step-by-Step Process​

Step 1: Authenticate and Get OAuth2 Bearer Token​

  • Generate an OAuth2 Bearer token by calling the /token endpoint with the POST HTTP method.
  • Use Basic Authentication with the client ID and client secret found in the settings section of your Jumio Portal.
  • Once obtained, include the token in the Authorization header for all subsequent API requests.
tip

Refer to the Authentication documentation for the specific endpoint to obtain this token.

Access Token URLs (OAuth2)​

Accept: application/json

Body (x-www-form-urlencoded)​

grant_type=client_credentials

Example Response​

{
  "access_token": "<your_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
note
  • OAuth 2.0 access tokens are valid for 60 minutes (3600 seconds) by default.
  • To avoid unnecessary authentication requests and reduce integration costs, do not call the /auth endpoint before every transaction. Instead, reuse the same access token until it expires, and request a new one only when needed.
  • For testing purposes, you can use Postman's built-in OAuth 2.0 authorization type (under the Authorization tab), which allows you to retrieve and manage tokens automatically across your requests or collections.
  • For a step-by-step walkthrough, check out this short video guide.

Step 2: Create or Update an Account​

Use the /accounts endpoint to initiate a new workflow for either a new or an existing user.

tip

A workflow defines which Jumio services will process your user's credentials.

New User​

Existing User​

Access Token URLs (OAuth2)​

Header​

Accept: application/json

Body (x-www-form-urlencoded)​

grant_type=client_credentials

Example Response​

{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    key": "10164" //ID + Selfie + Supporting Data
  }
}

Step 3: Initiate a Prepared Data Workflow for the Account​

Use the /accounts endpoint with the POST method along with your chosen workflowDefinition.key and customerInternalReference with respective key.

Endpoint

https://account.{{api_endpoint}}.jumio.ai/api/v1/accounts/{{accountId}}

Region-Specific Endpoints​

Example Request​

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

{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    "key": 10148
  }
}

Example Response​

{
   "timestamp": "2025-06-17T15:12:06.525Z",
   "account": {
       "id": "UUID"
   },
   "workflowExecution": {
       "id": "UUID",
       "credentials": [
           {
               "id": "UUID",
               "category": "DATA",
               "allowedChannels": [
                   "API"
               ],
               "api": {
                   "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOPQpCMRAE4LukduHtyyabtbO09QbJ_oBgpaKCeHfzvIHlDN_AvJO_Dve0T8hlQVml1dxq2qWuerTZZw-jlRsw1QYkLNDIFNitBxYsHWXjP4zZOhkVWLVPnGsGoUXBFxk2zNcaMfEz_B-uJ4-pb-fLw69b_o0Nh45oDja4A3E4jHkeRpCoObeBnD5fIy12X-AAAAA.2u6Ol6XjKcEpKjXnLkK1C7iwpeCpOgeEEfmgHhtdRvHTo-_EaV75l49-UjkIUZraMY7bP-q9QhPRAxhFUK17-A",
                   "parts": {
                       "prepared_data": "https://api.emea-1.jumio.link/api/v1/accounts/3efd4278-7468-4979-84dc-7edaf1515a19/workflow-executions/13da4d45-2ca8-4363-940c-e09bdbde26ff/credentials/d8e0ac83-4bb4-4d22-b529-67337fe7591c/parts/PREPARED_DATA"
                   },
                   "workflowExecution": "https://api.emea-1.jumio.link/api/v1/accounts/3efd4278-7468-4979-84dc-7edaf1515a19/workflow-executions/13da4d45-2ca8-4363-940c-e09bdbde26ff"
               }
           }
       ]
   }
}

Step 4: Upload Prepared Data​

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

note
  • If your workflow involves ID, selfie, or document checks that are collected through Jumio’s user interface (SDK or Web), the prepared data must be submitted before initiating these checks.
  • To prevent SQL/XML injection threats, the character set [^<>"/;%|]` is not allowed in the prepared data body values for the following keys: firstName, lastName, middleName, paternalSurname, maternalSurname, email, and phoneNumber.

Prepared Data Upload URL​

POST /api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}/credentials/{credentialId}/parts/PREPARED_DATA

Example​

Example 1: Prepared Data: eKYC​
{
   "firstName": "Cortez",
   "lastName": "Crook",
   "email": "johndoe@gmail.com",
   "phoneNumber": "+8009376310",
   "dateOfBirth": "1990-08-10",
   "socialSecurityNumber": "999999999",
   "sex": "0",
   "address": {
       "line1": "1302 Fayette drive",
       "postalCode": "46816",
       "city": "Fort Wayne",
       "subdivision": "IN",
       "country": "USA"
   },
   "id": {
       "idNumber": "N1244572",
       "type": "DRIVER_LICENSE"
   },
   "kyc": {
       "registrationDate": "2016-06-07",
       "registrationIpAddress": "176.80.185.187"
   }
}
Example 2: Prepared Data: Email Risk​
{
   "email": "johndoe@gmail.com"
}

Example Response​

{
   "timestamp": "2025-06-17T15:13:54.025Z",
   "account": {
       "id": "UUID"
   },
   "workflowExecution": {
       "id": "UUID"
   },
   "api": {
       "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOPQpCMRAE4LukduHtyyabtbO09QbJ_oBgpaKCeHfzvIHlDN_AvJO_Dve0T8hlQVml1dxq2qWuerTZZw-jlRsw1QYkLNDIFNitBxYsHWXjP4zZOhkVWLVPnGsGoUXBFxk2zNcaMfEz_B-uJ4-pb-fLw69b_o0Nh45oDja4A3E4jHkeRpCoObeBnD5fIy12X-AAAAA.2u6Ol6XjKcEpKjXnLkK1C7iwpeCpOgeEEfmgHhtdRvHTo-_EaV75l49-UjkIUZraMY7bP-q9QhPRAxhFUK17-A",
       "parts": {},
       "workflowExecution": "https://api.emea-1.jumio.link/api/v1/accounts/3efd4278-7468-4979-84dc-7edaf1515a19/workflow-executions/13da4d45-2ca8-4363-940c-e09bdbde26ff"
   }
}

Step 5: Finalize the Transaction​

Finalize the workflow using the finalization endpoint

Endpoint URL

PUT https://api.{{region}}.jumio.link/api/v1/accounts/{{accountId}}/workflow-executions/{{workflowExecutionId}}

For guidance on using this approach, contact Jumio support.

Example Response

{
   "timestamp": "2025-06-17T15:19:08.980Z",
   "account": {
       "id": "UUID",
   },
   "workflowExecution": {
       "id": "UUID"
   }
}

Step 6: Wait for the Callback​

Jumio will send a callback when the workflow is complete. This only includes No PII data/non-sensitive data status info, so proceed to retrieve full details. You can check the callback here.

tip

Callback times vary by workflow—please wait accordingly. For Testing purposes you may use Webhooks as mentioned here.

Step 7: Retrieve the Workflow Details​

Once the workflow is completed and you’ve received the callback, retrieve the full decision and credential results using the workflowExecution endpoint.

{
   "workflow": {
       "id": "UUID",
       "status": "PROCESSED",
       "definitionKey": "10066",
       "userReference": "yourUser",
       "customerInternalReference": "transaction_1234"
   },
   "account": {
       "id": "UUID"
   },
   "createdAt": "2025-06-17T15:26:40.485Z",
   "startedAt": "2025-06-17T15:27:25.640Z",
   "completedAt": "2025-06-17T15:27:29.196Z",
   "credentials": [
       {
           "id": "UUID",
           "category": "DATA",
           "parts": [
               {
                   "classifier": "PREPARED_DATA",
                   "href": "https://retrieval.emea-1.jumio.ai/api/.../parts/PREPARED_DATA"
               }
           ]
       }
   ],
   "decision": {
       "type": "REJECTED",
       "details": {
           "label": "TXN_REJECTED"
       },
       "risk": {
           "score": 100
       }
   },
   "steps": {
       "href": "https://retrieval.emea-1.jumio.ai/.../steps"
   },
   "capabilities": {
       "emailVerification": [
           {
               "id": "UUID",
               "credentials": [
                   {
                       "id": "UUID",
                       "category": "DATA"
                   }
               ],
               "decision": {
                   "type": "REJECTED",
                   "details": {
                       "label": "HIGH_RISK"
                   }
               },
               "data": {
                   "emailVerificationStatus": "EmailInexistent",
                   "firstVerifiedAt": "2015-10-27T00:00:00.000Z",
                   "totalHits": "1",
                   "emailExists": false,
                   "domainExists": true,
                   "domainName": "jumio.com",
                   "domainCompany": "Jumio",
                   "domainRiskLevel": "LOW",
                   "domainCreationDate": "2004-03-30T07:07:55.000Z",
                   "advice": "DATA_REVIEW",
                   "domainCountry": "USA",
                   "domainCategory": "Technology",
                   "domainCorporate": true
               }                           }
                       ]
                   }
               ]
           }
       ]
   }
}

The response retrieved will contain the detailed outcome of the Prepared Data process.

For further details, advanced use cases, or support with customization, please refer to the complete API documentation or contact Jumio support.

Table of Contents