# Smart 2FA

## What is Smart 2FA?

Exclusively from Veratad, Smart 2FA℠ finally introduces two-factor authentication to customer onboarding. By combining the best of identity verification and two-factor, Smart 2FA delivers **the highest level** of surety that your customers are who they say they are.

## **This service is asynchronous** 

This service may include two requests: 

1. **Initial Request:** with this request you will start the session by sending the target. Once started the first thing that will happen is the user will receive the OTP either through call or SMS. You will get a session token in return to send back in the secondary request with the user's OTP entry. 
2. **Secondary Request:** with this request you will send the entered OTP to be scored. If successful the verification process will also occur and the final result is returned. 

## SMS or Call

You are able to send the OTP via SMS or Call by adjusting the service name on initial request. The service name will either be:

`PhoneMatch5.0.Smart2FA.SMS` 

`PhoneMatch5.0.Smart2FA.Call`

## Initial Request Parameters and example response

<mark style="color:green;">`POST`</mark> `https://production.idresponse.com/process/comprehensive/gateway`

#### Request Body

| Name                                      | Type   | Description                                                                  |
| ----------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| user<mark style="color:red;">\*</mark>    | string | Your account's API username                                                  |
| pass<mark style="color:red;">\*</mark>    | string | Your account's API password                                                  |
| service<mark style="color:red;">\*</mark> | string | The service name (PhoneMatch5.0.Smart2FA.SMS or PhoneMatch5.0.Smart2FA.Call) |
| reference                                 | string | A unique identifier for your customer                                        |
| target<mark style="color:red;">\*</mark>  | object | The individual being sent for verification                                   |
| fn<mark style="color:red;">\*</mark>      | string | The target's first name                                                      |
| ln<mark style="color:red;">\*</mark>      | object | The target's last name                                                       |
| addr                                      | string | The target's street address (line 1 and line 2)                              |
| city                                      | string | the target's city                                                            |
| state                                     | string | The target's state                                                           |
| zip                                       | string | The target's zip                                                             |
| dob                                       | string | The target's Date of Birth (YYYYMMDD format)                                 |
| ssn                                       | string | The target's SSN (either 4 or 9)                                             |
| phone<mark style="color:red;">\*</mark>   | string | The target's phone number                                                    |
| email                                     | string | The target's email address                                                   |
| age                                       | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.)           |
| options                                   | object | The OTP options                                                              |

{% tabs %}
{% tab title="200: OK When the OTP has been delivered successfully " %}

```javascript
{
    "output": {
        "outofband": {},
        "rescue": {}
    },
    "meta": {
        "confirmation": 127334139,
        "reference": "195599",
        "service": "PhoneMatch5.0.Smart2FA.SMS",
        "timestamp": "2022-03-08 09:39:38",
        "company": "Company, LLC",
        "user": "company@veratad.com"
    },
    "result": {
        "action": "PENDING",
        "detail": "MORE INFORMATION IS REQUIRED",
        "issues": []
    },
    "continuations": {
        "outofband": {
            "url": "/process/continue",
            "hint": "Enter the six-digit code",
            "prompt": "One Time Passcode",
            "template": {
                "token": "umge9844g0j5d6sebq08qif9isr0xzzl",
                "codematch": {
                    "key": null
                }
            },
            "instructions": "A code has been delivered to the provided number.  Please resubmit the code to complete the transaction."
        }
    }
}
```

{% endtab %}

{% tab title="200: OK When the OTP was not delivered" %}

```javascript
{
    "output": {
        "outofband": {},
        "rescue": {}
    },
    "meta": {
        "confirmation": 127334300,
        "reference": "195599",
        "service": "PhoneMatch5.0.Smart2FA.SMS",
        "timestamp": "2022-03-08 09:45:51",
        "company": "Veratad Technologies, LLC",
        "user": "root@veratad.com"
    },
    "result": {
        "action": "FAIL",
        "detail": "FAILED TO SEND TO NUMBER",
        "issues": []
    }
}
```

{% endtab %}
{% endtabs %}

## Initial Request Body Example

```javascript
{
      "user": "user@company.com",
      "pass": "PASSWORD",
      "service": "PhoneMatch5.0.Smart2FA.SMS",
      "reference": "12345 {A UNIQUE ID}",
      "options": {
	"outofband": {
	        "message": "Hello {fn}, your one-time password is {pin}", // this is the SMS message that will be delivered to the user
		"do_not_send_to_types": ["landline"] // you can block "landlines" for the SMS service here
	      }
	},
      "target":{
            "fn":"Barbara",
            "ln": "Miller",
            "phone": "2015106000"
          }
  }
```

## Initial Request Action and Detail Responses

| Action  | Detail                       | Description                                                                                                                                                 |
| ------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FAIL    | VOIP NOT ALLOWED             | The phone line type was detected as VOIP                                                                                                                    |
| FAIL    | SUPPRESSED SENDING CODE      | The phone line type discovered was found in the `do_not_send_to_types` array in the options block on request                                                |
| FAIL    | FAILED TO SEND TO NUMBER     | An issue occurred during OTP delivery and the code was never received by the user                                                                           |
| FAIL    | DATA CHECK FAILED            | The phone number is invalid                                                                                                                                 |
| PENDING | MORE INFORMATION IS REQUIRED | The line type is not VOIP, the number is valid and the OTP was delivered to the user. The transaction is now waiting for the secondary request to complete. |

## Secondary request parameters and responses

<mark style="color:green;">`POST`</mark> `https://production.idresponse.com/process/continue`

Return the OTP entered and the token that you received on the Initial response to complete the transaction

#### Request Body

| Name                                            | Type   | Description                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------- |
| token<mark style="color:red;">\*</mark>         | string | The session token returned on the initial response |
| codematch:key<mark style="color:red;">\*</mark> | string | The OTP value entered by the user                  |

{% tabs %}
{% tab title="200: OK PASS " %}

```javascript
{{
    "final": {
        "template": {
            "token": "631bg2jx4s7fjwceitituf9nw52yn6i7"
        },
        "url": "/process/status"
    },
    "meta": {
        "company": "Veratad Technologies, LLC",
        "confirmation": 127335232,
        "reference": "195599",
        "service": "PhoneMatch5.0.Smart2FA.SMS",
        "timestamp": "2022-03-08 10:17:55",
        "user": "user@company.com"
    },
    "output": {
        "codematch": {
            "key_matched": true
        }
    },
    "result": {
        "action": "PASS",
        "detail": "ALL CHECKS PASSED",
        "issues": [
            "OUT-OF-BAND SUCCESSFUL"
        ]
    }
}
```

{% endtab %}

{% tab title="200: OK REVIEW" %}

```javascript
{
    "final": {
        "template": {
            "token": "631bg2jx4s7fjwceitituf9nw52yn6i7"
        },
        "url": "/process/status"
    },
    "meta": {
        "company": "Veratad Technologies, LLC",
        "confirmation": 127335232,
        "reference": "195599",
        "service": "PhoneMatch5.0.Smart2FA.SMS",
        "timestamp": "2022-03-08 10:17:55",
        "user": "user@veratad.com"
    },
    "output": {
        "codematch": {
            "key_matched": true
        }
    },
    "result": {
        "action": "REVIEW",
        "detail": "TRANSACTION REQUIRES FURTHER ATTENTION",
        "issues": [
            "OUT-OF-BAND SUCCESSFUL",
            "ADDRESS CHECK FAILED"
        ]
    }
}
```

{% endtab %}

{% tab title="200: OK FAIL" %}

```javascript
{
    "final": {
        "template": {
            "token": "631bg2jx4s7fjwceitituf9nw52yn6i7"
        },
        "url": "/process/status"
    },
    "meta": {
        "company": "Veratad Technologies, LLC",
        "confirmation": 127335372,
        "reference": "195599",
        "service": "PhoneMatch5.0.Smart2FA.SMS",
        "timestamp": "2022-03-08 10:21:28",
        "user": "user@veratad.com"
    },
    "output": {
        "codematch": {
            "key_matched": true
        }
    },
    "result": {
        "action": "FAIL",
        "detail": "NO MATCH",
        "issues": [
            "OUT-OF-BAND SUCCESSFUL"
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Secondary Request Sample Body

```json
{
	"token": "631bg2jx4s7fjwceitituf9nw52yn6i7",
	"codematch": {
		"key": 12345
	}
}
```

## Secondary Request Action and Detail Responses

The following are all values that will be returned in the result object of the response.

| Action | Detail                                 | Description                                                                                                                                                                                                           |
| ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FAIL   | NO MATCH                               | No matching identity found in the data sources                                                                                                                                                                        |
| FAIL   | TARGET IS DECEASED                     | Target found as a deceased identity                                                                                                                                                                                   |
| FAIL   | FAILED OUT-OF-BAND CHECK               | The OTP entered did not match what was sent to the user                                                                                                                                                               |
| REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the `issues`object with a list of the identity attributes that did not match. See full list below |
| PASS   | ALL CHECKS PASSED                      | Target was found is not deceased and all submitted target attributes match                                                                                                                                            |

## Issues Responses

When a transaction returns as `REVIEW` then there will be a list of issues. This list can include any of the below values.

| Issue                | Description                                           |
| -------------------- | ----------------------------------------------------- |
| ADDRESS CHECK FAILED | The address provided does not match any on file       |
| DOB CHECK FAILED     | The Date of Birth provided does not match any on file |
| SSN CHECK FAILED     | The SSN provided does not math any on file            |
| PHONE CHECK FAILED   | The phone number provided does not match any on file  |
| EMAIL CHECK FAILED   | The email address provided does not match any on file |
| AGE CHECK FAILED     | The age found does not meet the age submitted         |

## Rules

PhoneMatch+Smart2FA will process with the default ruleset. Which is as follows:

{% hint style="success" %}
The ruleset will return a PASS when:

* All OTP checks have passed
* A match is found
* The target is not deceased
* The target has provided all valid identity attributes including phone number
  {% endhint %}

{% hint style="warning" %}
The ruleset will return a REVIEW when:

* A match is found
* The target is not deceased
* The OTP was delivered
* The OTP matched&#x20;
* The target's identity attributes do not all match

This result will also return an array of issues to notify you of exactly which target attributes provided did not match.
{% endhint %}

{% hint style="danger" %}
The  ruleset will return a FAIL when:

* A match is not found&#x20;
* The target is deceased
* The phone line type is not acceptable&#x20;
* The OTP is not able to be delivered&#x20;
* The OTP entered does not match the OTP sent&#x20;
  {% endhint %}

{% hint style="info" %}
The ruleset will return PENDING when:&#x20;

* The service is waiting for the next API call with session token&#x20;
  {% endhint %}

## Service Testing

Since this service requires a successful OTP process you must use real data and have access to the phone number provided. You will be allotted 250 free transactions for development purposes.