This is a reference manual and configuration guide for Jumio Authentication with facemap storage on customer premise. It describes the workflow and how to initiate an Authentication transaction.
This feature allows you to use Authentication with needing to store the ID Verification PII data in the Jumio infrastructure.
You will retrieve the facemap (which represents the face identity of the user) using the ID Verification Retrieval API or ID Verification Callback. This facemap needs to be stored in your system. When you want to authenticate this user, you will send us the facemap using our server to server API to create a new Authentication transaction. You can start the user journey in your mobile app or web journey. Once the user completes the face capture process we will perform our 3D liveness checks on the face and compare it with the facemap identity you provide in the API call. Results of this transaction will let you know if the person is live and is the same person that was onboarded on your system.
Information about changes to features and improvements documented in each release is available in our Revision history.
The following conditions must be met before using this feature:
- The original ID Verification transaction needs to be deleted
- That ID Verification transaction has to be
- verificationStatus = APPROVED_VERIFIED
- similarity = MATCH
- validity = TRUE
If you need this function enabled or are unsure if it is enabled on your account, please reach out to your Account Manager directly or contact the Jumio Support team at [email protected].
You must use either the callback or Retrieval API to get the facemap of a ID Verification transaction and store this on your system.
The callback parameter facemap contains an URL to the facemap of the transaction.
See Callback for ID Verification for further information.
The response parameter facemap will be returned when retrieving the details of a transaction.
See the ID Verification Retrieval API Implementation Guide for further details.
Call the RESTful API POST endpoint /initiateAuthentication with a JSON object containing the properties described below to create a transaction for each user. You will receive a JSON object in the response containing a new authentication transaction reference to start authentication.
HTTP Request Method: POST
REST URL (US): https://netverify.com/api/authentication/v1/facemap/initiate
REST URL (EU): https://lon.netverify.com/api/authentication/v1/facemap/initiate
REST URL (SGP): https://core-sgp.jumio.com/api/authentication/v1/facemap/initiate
enrollmentTransactionReference within 15 minutes only the last one will successfully work. For the first ones the user will not be able to finish them, they will get a final state of EXPIRED. |
|---|
Authentication API calls are protected using HTTP Basic Authentication. Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under Settings > API credentials.
The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see Supported cipher suites.
The following fields are required in the header section of your request:
Accept: application/json
Content-Type: multipart/form-data
Authorization: (see RFC 7617)
User-Agent: YourCompany YourApp/v1.0
ℹ️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting. |
|---|
Required items appear in bold font.
| Name | Type | Content-Type | Description |
|---|---|---|---|
| enrollmentMetadata | object | application/json | The metadata required to initiate an authentication transaction. See supported enrollmentMetadata values. |
| facemap | byte array | application/octet-stream | The enrollment facemap bytes. |
Required items appear in bold font.
| Value | enrollmentMetadata |
|---|---|
| enrollmentTransactionReference | The transaction reference from the onboarding ID verification to be used for authentication. This is the Jumio scan reference of the original ID Verification transaction. |
| userReference | Your internal reference for the user. |
| callbackUrl1 | Sends verification result to this URL upon completion. Overrides Callback URL in the Customer Portal. |
1 See URL constraints for Callback, Error, and Success URLs.
Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Required items appear in bold font.
| Name | Type | Max. length | Description |
|---|---|---|---|
| authenticationTransactionReference | String | 36 | Jumio reference number for the Authentication transaction. |
POST https://netverify.com/api/v4/initiateAuthentication/ HTTP/1.1
Accept: application/json
Content-Type: multipart/form-data
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundary7MA4YWxkTrZu0gW--,
Content-Disposition: form-data; name="facemap"; filename="facemap.bin"
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Content-Disposition: form-data; name="enrollmentMetadata"
{
"enrollmentMetadata": {
"enrollmentTransactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"userReference": "user_1234",
"callbackUrl": "https://www.yourcompany.com/callback"
}
}
------WebKitFormBoundary7MA4YWxkTrZu0gW--
{
"authenticationTransactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Call the RESTful API POST endpoint /initiateAuthentication with a JSON object containing the properties described below to create a transaction for each user. You will receive a JSON object in the response containing a new authentication transaction reference to start authentication.
HTTP Request Method: POST
REST URL (US): https://netverify.com/api/authentication/v1/facemap/initiate
REST URL (EU): https://lon.netverify.com/api/authentication/v1/facemap/initiate
REST URL (SGP): https://core-sgp.jumio.com/api/authentication/v1/facemap/initiate
enrollmentTransactionReference within 15 minutes only the last one will successfully work. For the first ones the user will not be able to finish them, they will get a final state of EXPIRED. |
|---|
Authentication API calls are protected using HTTP Basic Authentication. Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under Settings > API credentials.
The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see Supported cipher suites.
The following fields are required in the header section of your request:
Accept: application/json
Content-Type: multipart/form-data
Authorization: (see RFC 7617)
User-Agent: YourCompany YourApp/v1.0
ℹ️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting. |
|---|
Required items appear in bold font.
| Name | Type | Content-Type | Description |
|---|---|---|---|
| enrollmentMetadata | object | application/json | The metadata required to initiate an authentication transaction. See supported enrollmentMetadata values. |
| facemap | byte array | application/octet-stream | The enrollment facemap bytes. |
Required items appear in bold font.
| Value | enrollmentMetadata |
|---|---|
| enrollmentTransactionReference | The transaction reference from the onboarding ID verification to be used for authentication. This is the Jumio scan reference of the original ID Verification transaction. |
| userReference | Your internal reference for the user. |
| callbackUrl1 | Sends verification result to this URL upon completion. Overrides Callback URL in the Customer Portal. |
| successUrl1 | Redirects to this URL after a successful transaction. Overrides Success URL in the Customer Portal. |
| errorUrl1 | Redirects to this URL after an unsuccessful transaction. Overrides Error URL in the Customer Portal. |
| userReference2 | Your internal reference for the user. |
| locale | Renders content in the specified language. Overrides Default locale in the Customer Portal. See supported locale values. |
1 See URL constraints for Callback, Error, and Success URLs.
2 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.
Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Required items appear in bold font.
| Name | Type | Max. length | Description |
|---|---|---|---|
| authenticationTransactionReference | String | 36 | Jumio reference number for the Authentication transaction. |
| redirectUrl | String | 255 | URL used to load Authentication client. TBD |
POST https://netverify.com/api/v4/initiateAuthentication/ HTTP/1.1
Accept: application/json
Content-Type: multipart/form-data
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundary7MA4YWxkTrZu0gW--,
Content-Disposition: form-data; name="facemap"; filename="facemap.bin"
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Content-Disposition: form-data; name="enrollmentMetadata"
{
"enrollmentMetadata": {
"enrollmentTransactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"userReference": "transaction_1234", "callbackUrl": "https://www.yourcompany.com/callback",
"successUrl" : "https://www.yourcompany.com/success", "errorUrl" : "https://www.yourcompany.com/error",
"tokenLifetimeInMinutes": 5,"locale": "de"
}
}
------WebKitFormBoundary7MA4YWxkTrZu0gW--
{
"authenticationTransactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
"redirectUrl": "https://yourcompany.netverify.com/web/v4/app?authorizationToken=xxxxxxxxxxxxxxlocale=en-GB"
}
You can use the authenticationTransactionReference to start the Authentication workflow within the SDK, as long as the reference has not been finalized.
A transaction has been finalized once it has one of the final states:
- PASSED
- FAILED
- INVALID
- EXPIRED
Follow the instructions in our mobile guide to start the SDK workflow.
Follow the instructions in our mobile guide to start the SDK workflow.
Follow the instructions in our Web guide - Section "Displaying Authentication" to start the web workflow by using the redirectUrl you received before.
© Jumio Corp. 395 Page Mill Road, Suite 150, Palo Alto, CA 94306