Skip to main content

QuickStart Guide: Fastfill + Existing Credentials Verification

Fastfill enables customers to capture and extract ID data quickly and pre-fill user information (first name, last name, date of birth, etc.) without running fraud or authenticity checks.

To maintain complete security, customers must run the full ID Verification workflow after Fastfill by using the Existing Credentials workflow.

This guide explains how to authenticate, launch Fastfill, extract user data, and complete verification using the previously captured ID.

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 customer 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 Fastfill Transaction (Capture + Extraction Only)​

Fastfill is used strictly for fast data capture and extraction. It does not perform fraud detection or authenticity checks. Use the /accounts endpoint to initiate a Fastfill workflow definition (for example, workflow 10172)

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": 10172,
    },
    "web": {
        "href": "https://hosted.jumio.com/...",
        "successUrl": "https://yourapp.com/success",
        "errorUrl": "https://yourapp.com/error"
    }
}

Example Response​

{
  "timestamp": "ISO-8601 timestamp",
  "account": {
    "id": "UUID"
  },
  "web": {
    "href": "https://hosted.jumio.com/fastfill/..."
  }
}

Step 3: User Completes Fastfill Flow​

The end-user scans their ID. Data such as first name, last name, address, and date of birth is extracted automatically.

Key Benefits​

  • User onboarding becomes very fast (“Registrazione Veloce” in Italian)
  • Customer receives highly reliable, machine-extracted data
important

Fastfill does not run Fraud checks or Image checks.

Step 4: Retrieve Extracted Data (Optional)​

Use the Retrieval API to fetch the extracted ID data if needed.

GET /api/v1/accounts/{{workflow_account_id}}/workflow-executions/{{workflow_execution_id}}data

Step 5: Run Full ID Verification using Existing Credentials​

After Fastfill, run a complete Verification workflow using Existing Credentials, allowing Jumio to reuse:

  • the previously uploaded ID document
  • extracted data
  • images

This avoids asking the user to resubmit their ID. Use the Existing Credentials workflow, commonly after Fastfill.

Endpoint URL

PUT https://api.{{region}}.jumio.link/api/v1/accounts/{{accountId}}

Use a workflowDefinition key representing ID Verification, such as 10570 (or any customer-specific verification workflow).

Example Request​

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

Step 6: Workflow Finalization​

Once the supporting data has been uploaded, the workflow must be finalized to start the verification process. While integrating via API, you must explicitly call the finalization endpoint.

Example Finalization Call​


curl --location --request PUT 'https://api.amer-1.jumio.ai/api/v1/accounts/3adef3f9-b892-4f9c-9b81-f16e5e87230d/workflow-executions/692701a5-eedc-45ca-adb6-213c2f3c7acc' \
--header 'Authorization: Bearer xxx'

Step 7: Retrieve Final Verification Result​

Once processing is completed, retrieve the full results, including:

  • Verification status
  • Extracted data
  • Images
  • Reject reasons (if applicable)

Upon receiving the callback, consume the retrieval API with the GET HTTP method:

Once you receive the response from the Retrieval API, parse it to:

  • Determine the final status (e.g., passed, rejected, etc.). Learn more about risk scores here.
  • Review the extracted document data.
  • Take the appropriate next steps based on the results.

Example Response​

{
    "workflow": {
        "id": "UUID",
        "status": "PROCESSED",
        "definitionKey": "10570",
        "userReference": "MyUser",
        "customerInternalReference": "transaction_1234"
    },
    "account": {
        "id": "UUID"
    },
    "createdAt": "2022-11-28T23:45:02.528Z",
    "startedAt": "2022-11-28T23:50:37.221Z",
    "completedAt": "2022-11-28T23:50:55.232Z",
    "credentials": [
         {
            "id": "UUID",
            "category": "ID",
            "parts": [
                {
                    "classifier": "FRONT",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/FRONT"
                },
                {
                    "classifier": "BACK",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/BACK"
                }
            ],
            "consent": {
                "decisionAccepted": true,
                "collectedBy": "CUSTOMER"
            }
        }
    ],
    "decision": {
        "type": "WARNING",
        "details": {
            "label": "WARNING"
        },
        "risk": {
            "score": 50.0
        }
    },
    "consent": {
        "obtained": "yes",
        "obtainedAt": "2022-11-28T23:50:40.136Z"
    },
    "steps": {
        "href": "https://retrieval.amer-1.jumio.ai/.../steps"
    },
    "capabilities": {
        "extraction": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "DRIVING_LICENSE",
                    "subType": "REGULAR_DRIVING_LICENSE",
                    "issuingCountry": "USA",
                    "firstName": "JOHN JACOB",
                    "lastName": "SMITH",
                    "dateOfBirth": "1969-01-18",
                    "expiryDate": "2025-01-18",
                    "issuingDate": "2019-12-26",
                    "documentNumber": "N1234567",
                    "state": "CA",
                    "gender": "M",
                    "currentAge": "54"
                }
            }
        ],
        "usability": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "SELFIE"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ]
    }
}

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

Table of Contents