Quickstart Guide: Selfie+ID Verification Powered by selfie.DONE
selfie.DONE simplifies the identity verification experience by combining Liveness with Jumio’s ability to reuse a previously verified identity when the user meets the required criteria. This can reduce the need for users to repeatedly submit their identity documents while maintaining a secure verification experience.
With selfie.DONE available globally, this guide helps you choose and integrate the Selfie + ID Verification powered by selfie.DONE service for eligible use cases.
If you only need Selfie (Liveness) + ID Verification without selfie.DONE, see the ID+Selfie Verification page.
For more information about selfie.DONE,see the documentation here.
Supported Channels
- Channel: Web and Mobile SDKs (API channel not supported).
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: Obtain an OAuth2 Bearer Token
- Generate an OAuth2 Bearer token by calling the
/tokenendpoint 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.
Refer to the API Authentication documentation for the specific endpoint to obtain this token.
Access Token URLs (OAuth2)
- US: https://auth.amer-1.jumio.ai/oauth2/token
- EU: https://auth.emea-1.jumio.ai/oauth2/token
- SG: https://auth.apac-1.jumio.ai/oauth2/token
Header
Accept: application/json
Body (x-www-form-urlencoded)
grant_type=client_credentials
Example Response
{
"access_token": "<your_token>",
"expires_in": 3600,
"token_type": "Bearer"
}
- 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
/authendpoint 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.
A workflow defines which Jumio services will process your user's credentials.
New User
- US: POST https://account.amer-1.jumio.ai/api/v1/accounts
- EU: POST https://account.emea-1.jumio.ai/api/v1/accounts
- SG: POST https://account.apac-1.jumio.ai/api/v1/accounts
Existing User
- US: PUT https://account.amer-1.jumio.ai/api/v1/accounts/{{accountId}}
- EU: PUT https://account.emea-1.jumio.ai/api/v1/accounts/{{accountId}}
- SG: PUT https://account.apac-1.jumio.ai/api/v1/accounts/{{accountId}}
Header
Accept: application/json
Example Request
{
"customerInternalReference": "transaction_1234",
"workflowDefinition": {
"key": "11313" // Selfie+ID Verification with selfie.DONE
}
}
Example Response
Details
{
"timestamp": "2026-09-21T06:44:35.177Z",
"account": {
"id": "<YOUR ACCOUNTID>"
},
"web": {
"href": "https://web.amer-1.jumio.ai/web/client?baseUrl=<WEB_URL>"
},
"sdk": {
"token": "<YOUR SDK TOKEN>"
},
"workflowExecution": {
"id": "<WORKFLOW_EXECUTION_UUID>",
"credentials": [
{
"id": "<CREDENTIAL_UUID>",
"category": "DATA",
"allowedChannels": [
"API"
],
"api": {
"token": "<YOUR_TOKEN>",
"parts": {
"prepared_data": "https://api.amer-1.jumio.ai/api/v1/accounts/<ACCOUNT_UUID>/workflow-executions/<WORKFLOW_EXECUTION_UUID>/credentials/<CREDENTIAL_UUID>/parts/PREPARED_DATA"
},
"workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/<ACCOUNT_UUID>/workflow-executions/<WORKFLOW_EXECUTION_UUID>"
}
},
{
"id": "<UUID>",
"category": "FACEMAP",
"allowedChannels": [
"WEB",
"SDK"
]
},
{
"id": "<UUID>",
"category": "SELFIE",
"allowedChannels": [
"WEB",
"SDK"
]
},
{
"id": "<UUID>",
"category": "ID",
"allowedChannels": [
"WEB",
"SDK"
]
}
]
}
}
Step 3: Supported Search Criteria: Upload Prepared Data
The ability to trigger a reusable ID search depends on different combinations of user data supplied within Prepared Data. If the required data is not provided or Jumio does not find a matching user, the transaction automatically proceeds with a new ID scan.
Currently, there are three supported user data options available for selfie.DONE:
1. Name and Date of Birth (Recommended – Global)
2. Country-Specific Identification Number and country code
3. Name, Date of Birth, supported country-specific identification number and country code
Option 1: Using Name and Date of Birth (Recommended – Global)
Use the individual’s full name along with their date of birth. This search criterion is supported globally and is the recommended default for searches across all countries within your tenant account’s Accepted IDs configuration.
| Search Criteria | Applicable Countries | Required Fields in Prepared Data |
|---|---|---|
| Name + Date of Birth | IDs from all supported countries | firstName, middleName (if present on government-issued ID), lastName, dateOfBirth |
Example Request
{
"firstName": "pris****",
"middleName": "da***",
"lastName": "da*****",
"dateOfBirth": "1985-05-13"
}
Option 2. Using Country-specific Identification Number
selfie.DONE supports identifier-based reusable ID search for specific countries using country-specific unique identifiers. Identifier searches always use an exact match strategy.
| Search Criteria | Applicable Countries | Required Prepared Data Fields |
|---|---|---|
| CPF + Document Country | Brazil | personalNumber (CPF), addressCountry |
| CURP + Document Country | Mexico | personalNumber (CURP), addressCountry |
| PESEL + Document Country | Poland | personalNumber (PESEL), addressCountry |
| DNI + Document Country | Spain, Peru | personalNumber (DNI), addressCountry |
Best Practices
-
Country-specific identification numbers (such as CPF or CURP, etc.) approach should be used when the collection and use of such identifiers is prevalent as part of the onboarding process in a country, and users are okay to provide them. Examples: CPF number in Brazil or CURP in Mexico, etc.
-
Identifier-based searches are performed only if the Identification Number country is provided as part of the address country field within the Prepared data.
-
If the country is not provided as part of the addressCountry, the identifier search will not return a match, and the transaction will proceed with a standard ID verification flow.
-
Except for Brazil, identifier-based searches (personalNumber + addressCountry) generally have a lower likelihood of returning a reusable ID compared to First Name + Middle Name (if present in Govt. issued ID) + Last Name + Date of Birth–based searches.
-
In the current version, reusable ID search is limited to transactions originating in Mexico and South America. Users located in other regions must scan a new ID.
Example Request
{
"firstName": "pris****",
"middleName": "da***",
"lastName": "da*****",
"dateOfBirth": "1985-05-13",
"address": {
"country": "BRA"
}
}
Option 3: Using Name, Date of birth and supported country-specific identification number
Example Request
{
"firstName": "pris****",
"middleName": "da***",
"lastName": "da*****",
"personalNumber": "12345679",
"address": {
"country": "BRA"
}
}
Example Response
{
"timestamp": "2026-09-21T06:45:22.158Z",
"account": {
"id": "<ACCOUNT_ID>"
},
"workflowExecution": {
"id": "<WORKFLOW_EXECUTION_UUID>"
},
"api": {
"token": "<YOUR_TOKEN>",
"parts": {},
"workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/<ACCOUNT_UUID>/workflow-executions/<WORKFLOW_EXECUTION_UUID>"
}
}
Step 4: Launch the Workflow
The account creation response provides two 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
- iFrame: Embed the experience in your webpage
- WebView: Load the URL in a mobile app WebView component
<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.
Step 5: Wait for the Callback
Jumio will send a callback when the workflow is complete. This includes only No PII/non-sensitive status information, so proceed to retrieve full details. You can check the callback here.
Callback time varies by workflow - wait accordingly.
Step 6: Retrieve the Workflow Results
Upon receiving the callback, consume the retrieval API with the GET HTTP method:
- US:
https://retrieval.amer-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId} - EU:
https://retrieval.emea-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId} - SG:
https://retrieval.apac-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}
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
Details
{
"workflow": {
"id": "<UUID>",
"status": "PROCESSED",
"definitionKey": "11313",
"userReference": "tertiary",
"customerInternalReference": "Arizona",
"reportingCriteria": "Regional"
},
"account": {
"id": "<UUID>"
},
"createdAt": "2026-09-21T08:21:36.573Z",
"startedAt": "2026-09-21T08:22:48.371Z",
"completedAt": "2026-09-21T08:23:09.839Z",
"credentials": [
{
"id": "<UUID>",
"category": "DATA",
"parts": [
{
"classifier": "PREPARED_DATA",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/PREPARED_DATA"
}
]
},
{
"id": "<UUID>",
"category": "SELFIE",
"parts": [
{
"classifier": "FACE_CROPPED",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/FACE_CROPPED"
},
{
"classifier": "FACE",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/FACE"
}
]
},
{
"id": "<UUID>",
"category": "ID",
"reusableIdentity": {
"source": "JUMIO",
"status": "ID_ACCEPTED"
},
"parts": [
{
"classifier": "FRONT",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/FRONT"
},
{
"classifier": "BACK",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/BACK"
}
]
},
{
"id": "<UUID>",
"category": "FACEMAP",
"parts": [
{
"classifier": "FACEMAP"
},
{
"classifier": "LIVENESS_1",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/LIVENESS_1"
},
{
"classifier": "LIVENESS_3",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/LIVENESS_3"
},
...........
]
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
},
"risk": {
"score": 0.0
}
},
"steps": {
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/workflow-executions/<UUID>/steps"
},
"capabilities": {
"extraction": [
{
"id": "<UUID>",
"credentials": [
{
"id": "<UUID>",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "ID_CARD",
"subType": "NATIONAL_ID",
"issuingCountry": "BRA",
"firstName": "N/A",
"lastName": "Joe",
"dateOfBirth": "1962-03-14",
"documentNumber": "2686346XX",
"cpf": "731429611XX",
"currentAge": "64"
}
}
],
"classification": [
{
"id": "<UUID>",
"credentials": [
{
"id": "<UUID>",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"country": "BRA",
"type": "ID_CARD",
"subType": "NATIONAL_ID",
"printedDocumentName": "CARTEIRA DE IDENTIDADE",
"firstIssueDate": "2016-04-06",
"hasCryptoChip": false,
"isFoldable": false,
"isHandwritten": false,
"layout": "LANDSCAPE",
"material": "PAPER"
}
}
],
"similarity": [
{
"id": "<UUID>",
"credentials": [
{
"id": "<UUID>",
"category": "SELFIE"
},
{
"id": "<UUID>",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "MATCH"
}
},
"data": {
"similarity": "MATCH"
}
}
],
"liveness": [
{
"id": "<UUID>",
"validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/credentials/<UUID>/parts/FACEMAP",
"credentials": [
{
"id": "<UUID>",
"category": "SELFIE"
},
{
"id": "<UUID>",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "JUMIO_PREMIUM",
"predictedAge": 27,
"ageConfidenceRange": "19-40"
}
}
],
"dataChecks": [
{
"id": "<UUID>",
"credentials": [
{
"id": "<UUID>",
"category": "ID"
}
],
"decision": {
"type": "NOT_EXECUTED",
"details": {
"label": "PRECONDITION_NOT_FULFILLED"
}
}
}
],
"imageChecks": [
{
"id": "<UUID>",
"credentials": [
{
"id": "<UUID>",
"category": "SELFIE"
},
{
"id": "<UUID>",
"category": "ID"
}
],
"decision": {
"type": "REJECTED",
"details": {
"label": "MANIPULATED_DOCUMENT"
},
"additionalInformation": "fuzzyDataMatchingFraudRule"
},
"data": {
"faceSearchFindings": {
"status": "DONE",
"findings": [
"29b3c3e1-6a83-........",
"8bfb9f15-c3c6-........",
"f0a4f3db-cf86-........",
"d9562614-28f5-........",
"57373245-e187-........",
"0e672369-188e-........",
"6376606b-fb52-........"
]
}
}
}
],
"usability": [
{
"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"
}
}
},
{
"id": "<UUID>",
"credentials": [
{
"id": "<UUID>",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
],
"lookups": [
{
"id": "<UUID>",
"credentials": [
{
"id": "<UUID>",
"category": "SELFIE"
},
{
"id": "<UUID>",
"category": "DATA"
},
{
"id": "<UUID>",
"category": "ID"
}
],
"decision": {
"type": "REJECTED",
"details": {
"label": "REJECTED"
}
},
"data": {
"matchedTransactions": {
"totalHighRiskTransactions": 0,
"totalMediumRiskTransactions": 0,
"totalLowRiskTransactions": 2,
"earliestTransactionTime": "2025-10-16T13:10:06.973Z",
"latestTransactionTime": "2025-12-22T08:00:25.547Z",
"network": {
"highRiskTransactions": 0,
"mediumRiskTransactions": 0,
"lowRiskTransactions": 2,
"earliestTransactionTime": "2025-10-16T13:10:06.973Z",
"latestTransactionTime": "2025-12-22T08:00:25.547Z",
"transactions": [
"29b3c3e1-6a83-48d6-86d1-......",
"67c9dda4-f49b-4e4f-a4c8-....."
]
},
"associatedNetwork": {
"highRiskTransactions": 0,
"mediumRiskTransactions": 0,
"lowRiskTransactions": 0
}
},
"faceMatchedTransactions": {
"totalHighRiskTransactions": 0,
"totalMediumRiskTransactions": 0,
"totalLowRiskTransactions": 2,
"earliestTransactionTime": "2025-10-16T13:10:06.973Z",
"latestTransactionTime": "2025-12-22T08:00:25.547Z",
"network": {
"highRiskTransactions": 0,
"mediumRiskTransactions": 0,
"lowRiskTransactions": 2,
"earliestTransactionTime": "2025-10-16T13:10:06.973Z",
"latestTransactionTime": "2025-12-22T08:00:25.547Z",
"transactions": [
"29b3c3e1-6a83-48d6-86d1-........",
"67c9dda4-f49b-4e4f-a4c8-........"
]
},
"associatedNetwork": {
"highRiskTransactions": 0,
"mediumRiskTransactions": 0,
"lowRiskTransactions": 0
}
},
"matchedImagesTransactions": {
"totalHighRiskTransactions": 0,
"totalMediumRiskTransactions": 0,
"totalLowRiskTransactions": 1,
"earliestTransactionTime": "2026-09-16T07:53:33.027Z",
"latestTransactionTime": "2026-09-16T07:53:33.027Z",
"network": {
"highRiskTransactions": 0,
"mediumRiskTransactions": 0,
"lowRiskTransactions": 1,
"earliestTransactionTime": "2026-09-16T07:53:33.027Z",
"latestTransactionTime": "2026-09-16T07:53:33.027Z",
"transactions": [
"0e672369-188e-4224-9474-........"
]
},
"associatedNetwork": {
"highRiskTransactions": 0,
"mediumRiskTransactions": 0,
"lowRiskTransactions": 0
}
}
}
}
]
},
"rules": {
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/<UUID>/workflow-executions/<UUID>/rules",
"executions": [
{
"id": "<UUID>",
"startedAt": "2026-09-21T08:23:09.345Z",
"completedAt": "2026-09-21T08:23:09.821Z",
"rulesets": [
{
"id": "<UUID>",
"name": "Usability Rules Test",
"version": 1,
"score": 0,
"rulesNotMatched": [
{
"id": "<UUID>",
"name": "Usability ID Decision - Rejected",
"version": 1,
"score": 100
}
]
}
]
},
{
"id": "<UUID>",
"startedAt": "2026-09-21T08:23:08.811Z",
"completedAt": "2026-09-21T08:23:09.329Z",
"rulesets": [
{
"id": "<UUID>",
"name": "Jumio Master Ruleset 2",
"version": 1,
"score": 350,
"rulesMatched": [
{
"id": "<UUID>",
"name": "Image Checks Decision Type - Rejected",
"version": 1,
"score": 100
},
{
"id": "<UUID>",
"name": "Current Age to Predicted Age - gap is greater than 20",
"version": 1,
"score": 50
},
{
"id": "<UUID>",
"name": "Data Checks Decision Type - Not Executed",
"version": 1,
"score": 100
},
{
"id": "<UUID>",
"name": "Extraction ID Sub Type - National ID",
"version": 1,
"score": 0
},
{
"id": "<UUID>",
"name": "Image Checks Decision Label - Manipulated Document",
"version": 1,
"score": 100
}
],
"rulesNotMatched": [
{
"id": "<UUID>",
"name": "Phone Type - Invalid",
"version": 1,
"score": 50
},
......................
]
}
]
}
]
}
}