Quickstart Guide: ID + Selfie Verification
Follow these steps to authenticate, create or update account, launch identity verification workflows, and handle the response.
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
Authorizationheader for all subsequent API requests.
tip
Refer to the 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"
}
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
/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.
info
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": "10164" //ID + Selfie + Supporting Data
}
}
Example Response
{
"timestamp": "ISO-8601 timestamp",
"account": {
"id": "string"
},
"web": {
"href": "https://hosted.jumio.com/...",
"successUrl": "https://yourapp.com/success",
"errorUrl": "https://yourapp.com/error"
},
"sdk": {
"token": "JWT token"
},
"workflowExecution": {
"id": "string",
"credentials": [
{
"id": "string",
"category": "ID | DATA | SELFIE | FACEMAP",
"label": "string",
"allowedChannels": ["WEB", "API", "SDK"],
"api": {
"token": "JWT token",
"workflowExecution": "https://api.jumio.ai/.../workflow-executions/{id}",
"parts": {
"front": "https://.../parts/FRONT",
"back": "https://.../parts/BACK",
"prepared_data": "https://.../parts/PREPARED_DATA",
"face": "https://.../parts/FACE"
}
}
}
]
}
}
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
- 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.
Option 3: Build Custom Interface with API
Use the workflowExecution.api.workflowExecution endpoint to upload images directly. You'll need to:
- Upload front, back, and selfie images.
- Finalize the workflow using the finalization endpoint.
For guidance on using this approach, contact Jumio support.
Step 4: 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.
note
Callback time varies by workflow—wait accordingly.
Step 5: 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": "10011",
"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": "SELFIE",
"parts": [
{
"classifier": "FACE",
"href": "https://retrieval.amer-1.jumio.ai/.../parts/FACE"
}
],
"consent": {
"decisionAccepted": true,
"collectedBy": "CUSTOMER"
}
},
{
"id": "UUID",
"category": "FACEMAP",
"parts": [
{
"classifier": "FACEMAP"
},
{
"classifier": "LIVENESS_1",
"href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_1"
},
{
"classifier": "LIVENESS_3",
"href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_3"
},
{
"classifier": "LIVENESS_2",
"href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_2"
},
{
"classifier": "LIVENESS_5",
"href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_5"
},
{
"classifier": "LIVENESS_4",
"href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_4"
},
{
"classifier": "LIVENESS_6",
"href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_6"
}
],
"consent": {
"decisionAccepted": true,
"collectedBy": "CUSTOMER"
}
},
{
"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"
}
}
],
"similarity": [
{
"id": "UUID",
"credentials": [
{
"id": "UUID",
"category": "SELFIE"
},
{
"id": "UUID",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "MATCH"
}
},
"data": {
"similarity": "MATCH"
}
}
],
"liveness": [
{
"id": "UUID",
"credentials": [
{
"id": "UUID",
"category": "SELFIE"
},
{
"id": "UUID",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "JUMIO_STANDARD",
"predictedAge": 44,
"ageConfidenceRange": "14-67"
}
}
],
"dataChecks": [
{
"id": "UUID",
"credentials": [
{
"id": "UUID",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
],
"imageChecks": [
{
"id": "UUID",
"credentials": [
{
"id": "UUID",
"category": "SELFIE"
},
{
"id": "UUID",
"category": "ID"
}
],
"decision": {
"type": "WARNING",
"details": {
"label": "REPEATED_FACE"
}
},
"data": {
"faceSearchFindings": {
"status": "DONE",
"findings": [
"22771260-8cb0-42a2-a38a-d8f853063cc2",
"27232651-4b18-4cf1-8d4a-df0451abc717",
"9541ae91-834e-4914-a30d-6534fed4eb6d",
"9414413d-2c76-44d2-9052-8876fa327a02"
]
}
}
}
],
"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.