Call

Validate a user's number and send a one time password via call to their phone to verify they have possession.

This service is asynchronous

The PhoneMatch OTP delivery services are asynchronous which means you will make an initial call to send the OTP and receive a response and a second call to validate the user's OTP entry against what was sent.

  1. Initial Request - Send the phone number with other options via the Initial Request Instructions below and when successful you will receive a response with a template that includes a token value.

  2. OTP Validation Request - Send the template returned in the initial request including the token and the user's OTP entry back to the system for final match result.

As part of this process you are also validating the number the user provided since the service will not send to invalid phone lines.

PhoneMatch5.0.Call (initial request)

POST https://production.idresponse.com/process/comprehensive/gateway

Initial request details

Request Body

{
  "output": {
    "outofband": {}
  },
  "meta": {
    "confirmation": 57984073,
    "reference": "12345",
    "service": "PhoneMatch5.0.Call",
    "timestamp": "2019-01-07 12:35:09",
    "company": "Company ABC, Inc.",
    "user": "user@company.com"
  },
  "result": {
    "action": "PENDING",
    "detail": "MORE INFORMATION IS REQUIRED",
    "issues": []
  },
  "continuations": {
    "outofband": {
      "url": "/process/continue",
      "template": {
        "token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1",
        "codematch": {
          "key": null
        }
      },
      "instructions": "A code has been delivered to the provided number.  Please resubmit the code to complete the transaction."
    }
  }
}

Sample Initial Request Body

{
    "user": "user@company.com",
    "pass": "PASSWORD",
    "service": "PhoneMatch5.0.Call",
    "reference": "12345",
    "options": {
        "outofband": {
            "do_not_send_to_types": ["voip", "mobile", "landline"],
            "country": {
			"blacklist": ["ISO2 Country Code"], //countires you do not want to send codes  
                	"whitelist": ["ISO2 Country Code"] //countires you only want to send codes
		}
        }
    },
    "target": {
        "fn": "John",
        "ln": "Smith",
        "phone": "2015106000"
    }
}

Action and Detail Responses Initial Request

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

PhoneMatch5.0.Call (OTP validation request)

POST https://production.idresponse.com/process/continue

OTP validation request details

Request Body

{
    "final": {
        "template": {
            "token": "1x6mvu6b4kuwonduqw8b1nsj7jpxgaza"
        },
        "url": "\/process\/status"
    },
    "meta": {
        "company": "Veratad Technologies, LLC",
        "confirmation": 96197373,
        "reference": null,
        "service": "PhoneMatch5.0.SMS",
        "timestamp": "2020-07-10 10:46:08",
        "user": "root@veratad.com"
    },
    "output": {
        "codematch": {
            "key_matched": true
        }
    },
    "result": {
        "action": "PASS",
        "detail": "ALL CHECKS PASSED",
        "issues": []
    }
}

Sample OTP Validation Request Body

{
    "token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1",
    "codematch": {
        "key": "12345"
    }
}

Action and Detail Response OTP Validation Request

Rules

PhoneMatch+SMS will process with the default base ruleset:

The base ruleset will return a PASS when:

  • The phone number is valid

  • The phone line type is not found in the do_not_send_to_types array

  • The OTP was sent successfully

  • The user OTP entry matched the OTP sent

The base ruleset will return a PENDING when:

  • The phone number is valid

  • The phone line type is not found in the do_not_send_to_types array

  • The OTP was sent successfully

  • The transaction is waiting for submission of the user's OTP entry

The base ruleset will return a FAIL when:

  • The phone number is not valid

  • The phone line type is found in the do_not_send_to_types array

  • The OTP was not sent successfully

  • The user OTP entry did not match the OTP sent

Last updated