Skip to main content

Quickstart Guide: Doc Proof

This guide outlines the essential steps to integrate Jumio's Doc Proof, utilizing OAuth 2.0 authentication and the Jumio-hosted user experience (Web or SDK). It includes the process of setting up prepared data, launching the workflow, and handling the results.

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.
note

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: Initiate a Doc Proof Workflow​

Use the /accounts endpoint to initiate a doc proof 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 Request​

{
    "customerInternalReference":"transaction_1234",
    "workflowDefinition":{
        "key": 10170,
        "credentials": [
            {
                "category": "DOCUMENT",
                "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA"]
                },
                "type": {
                    "predefinedType": "DEFINED",
                    "values": ["BS"]
                }
            }
        ]
    },
}
  • workflowDefinition: Specifies the workflow configuration. -- workflowDefinition.key: Set to 10170 to activate the Doc Proof and Multi Doc Upload Image upload, NO data extraction, NO fraud checks). -- type: Defines the specific document type to be requested from the user. The Document Code may be, (Bank Statement): "BS", Example (Utility Bill): "UB" etc.,

Note: Refer to the Supported Documents for the complete and up-to-date list of supported document codes.

Example Response​

The JSON response will contain URLs and tokens for different integration channels:

  • web.href: URL for Jumio's hosted web client. Redirect user or embed in an <iframe>/WebView.
  • SDK.token: Token for initializing Jumio's Web or Native Mobile SDK.
  • API.workflowExecution: Base URL for direct API image uploads.
{
    "timestamp": "2025-06-17T15:59:29.997Z",
    "account": {
        "id": "790e9aee-99ee-45ae-8ca4-4f82cf862f31"
    },
    "web": {
        "href": "https://jumio-go.web.emea-1.jumio.ai/web/client?baseUrl=https%3A%2F%2Fweb-sdk.emea-1.jumio.ai%2Fwebsdk%2Fv4%2Fapi&authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg&locale=it"
    },
    "sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg"
    },
    "workflowExecution": {
        "id": "0a3ccbad-da8a-4048-a589-81281d1f13f6",
        "credentials": [
            {
                "id": "61ec602b-3f68-40a6-b3b9-db2d1b26a2f5",
                "category": "DATA",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg",
                    "parts": {
                        "prepared_data": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6/credentials/61ec602b-3f68-40a6-b3b9-db2d1b26a2f5/parts/PREPARED_DATA"
                    },
                    "workflowExecution": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6"
                }
            },
            {
                "id": "2dc87b73-3eb4-4828-a840-cd0ce7bbf909",
                "category": "DOCUMENT",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg",
                    "parts": {
                        "document": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6/credentials/2dc87b73-3eb4-4828-a840-cd0ce7bbf909/parts"
                    },
                    "workflowExecution": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6"
                }
            }
        ]
    }
}

Step 3: Launch the Workflow​

The account creation response provides three integration options:

Option 1: Use Jumio's Hosted Interface​

Use workflowExecution.web.href in one of these ways:

  • Redirect: Send users to the URL in a new browser tab
  • WebView: Load the URL in a mobile app WebView component
  • iFrame: Embed the experience in your webpage
<iframe src="https://hosted.jumio.com/workflow/abc123" width="100%" height="700"></iframe>

Option 2: Integrate Jumio SDKs​

Initialize the SDK using workflowExecution.sdk.token. Refer to the Jumio SDK documentation for implementation details.

Option 3: Build Custom Interface with API​

Use the workflowExecution.api.workflowExecution endpoint to upload images directly. 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.

Step 4: Callback Handling​

  1. Jumio will send a POST request to the configured callback URL upon workflow completion.
  2. You will receive callbacks for Doc Proof once the workflow is completed.
  3. The callback payload contains limited information and primarily serves as a notification of workflow completion.

Step 5: Retrieve Workflow Details​

Upon receiving the callback, make an immediate GET request to the Retrieval API. To consume the "Workflow Details," refer to the Retrieval API Endpoint. You will likely need to include a workflow ID (potentially available in the callback or the initial account creation response).

The response retrieved will contain the detailed outcome of the Doc Proof process, including verification status, extracted data (if applicable), and any rejection reasons or error codes.

{
   "workflow": {
       "id": "string",
       "status": "PROCESSED",
       "definitionKey": "10026",
       "userReference": "mandatory user reference",
       "customerInternalReference": "transaction_1234"
   },
   "account": {
       "id": "string"
   },
   "createdAt": "2025-06-17T08:35:55.121Z",
   "startedAt": "2025-06-17T08:36:57.629Z",
   "completedAt": "2025-06-17T08:36:58.239Z",
   "credentials": [
       {
           "id": "string",
           "category": "DOCUMENT",
           "parts": [
               {
                   "classifier": "1",
                   "href": "https://retrieval.emea-1.jumio.ai/.../parts/1"
               }
           ]
       }
   ],
   "decision": {
       "type": "PASSED",
       "details": {
           "label": "PASSED"
       },
       "risk": {
           "score": 0.0
       }
   },
   "steps": {
       "href": "https://retrieval.emea-1.jumio.ai/.../steps"
   },
   "capabilities": {}
}

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

Table of Contents