Skip to main content

Use Existing Credentials

In the Jumio platform, customers can reuse ID, Selfie, and Facemap Credentials from previous transactions for subsequent transactions—whether performed via web, mobile, or API channels.

To be eligible for reuse, two conditions must be met,

  • The original Credential must have successfully passed usability checks.
  • Explicit user consent must have been obtained for the data.
note

This feature supports the entire Credential, not individual parts of it. If a workflow does not require any new Credentials and all existing Credentials are reused, the workflow will be automatically finalized. In this case, you can initialize the workflow using the account update API and either wait for the callback or call retrieval directly.

Consent must be enabled to use this feature. The original transaction, in which the credential was provided to KYX, must include recorded consent.

Channel Support​

Existing-credential workflows are supported through API and SDK channels. Use these channels to ensure proper functionality.

Multi-Credential Support​

Workflows function best when each credential type is provided only once. Ensure there’s no duplication of credential types in the same workflow.

Credential Support​

CredentialExisting Credential SupportedPreconditions
IDYesUsability PASSED, Consent Provided
FACEMAPYesUsability PASSED, Consent Provided
SELFIEYesUsability PASSED, Consent Provided

Setting Up a Workflow with Existing Credentials​

When creating a workflow in Jumio Designer, you can select whether to use an existing credential.

Initialization​

  • By default, the latest credential for that category on the account will be used.
  • If the credential (ID, SELFIE, FACEMAP) is usable, it will be applied automatically; otherwise, an error will occur during initialization.
  • You can also specify a credential explicitly using its credential identifier (uuid), which is included in the retrieval response of previous workflows.

Auto-Finalization​

If all credentials are existing, the workflow will be finalized automatically. After performing an account update, you do not need to call the finalization API.

Sample workflows: 10112, 10113, 10114, 10115

Sample Requests​

Request 1: Account update – default (latest credential used)​

This request uses the normal account update payload. The latest credential of each type will be used automatically if usable.

Request 2: Account update – specific credential IDs​

This request explicitly specifies which credential IDs to use for the transaction.

{
  "customerInternalReference": "myTransactionReference",
  "workflowDefinition": {
    "key": 10113
  },
  "userConsent": {
    "userIp": "xxx.80.211.xxx",
    "userLocation": {
      "country": "USA",
      "state": "IL"
    },
    "consent": {
      "obtained": "yes",
      "obtainedAt": "2023-03-20T17:20:35.000Z"
    }
  },
  "userReference": "myUserReference"
}

Sample Responses​

Case 1: When some credentials need to be uploaded​

In this scenario, some credentials already exist, while others must be uploaded by the end user. The account update response includes upload links only for the credentials that require new uploads.

Case 2: When all credentials already exist​

If all required credentials are available, no upload links are included and processing starts immediately. Finalization is not required.

{
  "timestamp": "2023-09-08T06:30:52.164Z",
  "account": {
    "id": "89d585b9-ab3e-4de8-bb39-d79ecda2bfa7"
  },
  "workflowExecution": {
    "id": "bc6d862e-a1ae-40fa-9781-8fc755f75976",
    "credentials": [
      {
        "id": "b701e6c5-b74c-434a-866a-ef1f084a4d80",
        "category": "ID",
        "allowedChannels": ["WEB", "API", "SDK"],
        "api": {
          "token": "<>",
          "parts": {
            "front": "https://api.emea-1.jumio.link/api/v1/accounts/89d585b9-ab3e-4de8-bb39-d79ecda2bfa7/workflow-executions/bc6d862e-a1ae-40fa-9781-8fc755f75976/credentials/b701e6c5-b74c-434a-866a-ef1f084a4d80/parts/FRONT",
            "back": "https://api.emea-1.jumio.link/api/v1/accounts/89d585b9-ab3e-4de8-bb39-d79ecda2bfa7/workflow-executions/bc6d862e-a1ae-40fa-9781-8fc755f75976/credentials/b701e6c5-b74c-434a-866a-ef1f084a4d80/parts/BACK"
          },
          "workflowExecution": "https://api.emea-1.jumio.link/api/v1/accounts/89d585b9-ab3e-4de8-bb39-d79ecda2bfa7/workflow-executions/bc6d862e-a1ae-40fa-9781-8fc755f75976"
        }
      },
      {
        "id": "b701e6c5-b74c-434a-866a-ef1f084a4d80",
        "category": "SELFIE",
        "allowedChannels": []
      }
    ]
  }
}

Sample Error Responses​

Error 1: Account initiate used instead of account update​

{
  "type": "about:blank",
  "title": "Bad Request: Workflow [10113] requires [ID, SELFIE] existing credentials therefore no new account can be created. The update account endpoint has to be used instead",
  "status": "400",
  "detail": "[]",
  "instance": "/api/v1/accounts"
}

Error 2: Account update used but credentials are unusable​

{
  "type": "about:blank",
  "title": "Bad Request: Workflow 10115 requires [ID] existing credentials but  [ID] are unusable for the account 02e2c457-9424-43dd-b691-c1a9167a4144",
  "status": "400",
  "detail": "[]",
  "instance": "/api/v1/accounts/02e2c457-9424-43dd-b691-c1a9167a4144"
}

Error 3: Account update used but credential ID is invalid​

{
  "type": "about:blank",
  "title": "Bad Request: JSON parse error: Cannot deserialize value of type `java.util.UUID` from String dfxcv-faddf-cdfsfds-sdsdfa: UUID has to be represented by standard 36-char representation",
  "status": "400",
  "detail": "[]",
  "instance": "/api/v1/accounts/02e2c457-9424-43dd-b691-c1a9167a4144"
}
warning

If an eIDAS digital ID is used instead of a physical ID, the system does not have access to the ID face, meaning (face comparison) Similarity Checks cannot be performed. The actual ID image is also not returned. Additionally, the data points returned may differ when using an eIDAS digital ID. For risk scoring, this limitation may need to be addressed in your rules configuration. Credential reusability is also not supported when using an eIDAS digital ID.

Table of Contents