How to Approve Real Users and Block Fake Accounts at Sign Up with Lookup and Verify in PHP

Time to read:

August 31, 2026

Written by

Twilion

How to Approve Real Users and Block Fake Accounts at Sign Up with Lookup and Verify in PHP

By implementing onboarding intelligence with Twilio Lookup and phone verification with Twilio Verify, you can build seamless sign ups and higher pass rates while still blocking fraud. Combining multiple fraud checks like detecting line type and proving phone number possession into one flow creates a resilient yet frictionless defense layer to block fake accounts while ensuring a smooth path for real users.

By the end of this tutorial you will have a working PHP example that can collect a user's name and phone number and conduct a multi-step orchestrated identity verification flow. You can also find the completed code on GitHub.

Prerequisites to building with Twilio Lookup and Verify

To code along with this post you will need:

PHP 8.5
Your Twilio Account SID and Auth Token. Grab them from the Twilio Console
Lookup Identity match access (no additional access requirements for US & Brazilian numbers, but may require carrier approval elsewhere)
[Optional] Lookup Line Status access
A Verify Service SID - create one in the console or with the following API request:

curl -X POST "https://verify.twilio.com/v2/Services" \
  --data-urlencode "FriendlyName=My Verify Service" \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

If you're testing outside of the US and Brazil, you may see Error 60619: Lookup Request Cannot be Completed in Twilio Region. To bypass this, you will need carrier approval for Lookup Identity Match. Alternatively, you can use our sandbox experience with test credentials and magic numbers.

Set up your PHP project

Now create your project to build a trusted sign-up flow:

composer create-project settermjd/twilio-slim-base-project twilio-trusted-signups
cd twilio-trusted-signups
mkdir -p data src/templates

Then, create a .env file and add the following keys:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
IDENTITY_MATCH_ENABLED="false"
LINE_STATUS_ENABLED="false"

Building the Verification Pipeline

This project will codify 4 layers of checks on a phone number during sign up. The best part is that the user won't know 3 of them are happening and they get progressively more intense so we're filtering out bad actors faster and cheaply before taking more drastic actions.

Here's a look at what we're building:

Process flow diagram for orchestrating onboarding intelligence

Step 1 - Check the line type

First, use the Lookup API line type intelligence package to make sure we're dealing with a mobile number. The code explicitly filters out landlines, nonfixed VoIP, toll free, (and pagers for fun) but you can customize this easily. Learn more about potential line types the API can return in the documentation.

Step 2 - [Optional] Check the line status

Then make sure the line is reachable. Use the Lookup API line status package to filter out inactive and unreachable numbers. Note — this is commented out by default in the code below since it is in Private Beta and requires an extra step to get access. To request access for Lookup Line Status, submit this form. After that, in .env set LINE_STATUS_ENABLED to "true".

Step 3 - Match the name to the phone number

In the last of our background checks, use the Lookup API Identity Match package to verify that the submitted name matches the phone number. Identity Match compares user-supplied data against authoritative sources for a zero-knowledge result, in other words a way to verify the data’s accuracy without revealing the underlying data. Check the individual firstNameMatch and lastNameMatch fields directly and require each to be either exact_match or high_partial_match. This allows common variations like nicknames or middle names used as a first name, while still rejecting mismatches. Any other result (a no_match, partial_match, or null) will reject the request.

You can change these requirements to fit your business logic or reduce false negatives. Learn more about Identity Match field values in the documentation.

To enable that check in the code, in .env set IDENTITY_MATCH_ENABLED to "true".

Step 4 - Phone verification

If all of the lookup steps pass, the user will receive an OTP and complete a standard phone verification flow.

To implement all four steps, first, replace the code in public/index.php with the following code:

<?php

declare(strict_types=1);

use App\Application;
use DI\Container;
use Dotenv\Dotenv;
use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Monolog\Logger;
use Psr\Log\LoggerInterface;
use Slim\Factory\AppFactory;
use Slim\Flash\Messages;
use Slim\Views\Twig;
use Slim\Views\TwigMiddleware;
use Twilio\Rest\Client;

require __DIR__ . '/../vendor/autoload.php';

$dotenv = Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();
$dotenv->required('IDENTITY_MATCH_ENABLED')->notEmpty()->isBoolean();
$dotenv->required('LINE_STATUS_ENABLED')->notEmpty()->isBoolean();

$container = new Container();

$client = new Client($_ENV['TWILIO_ACCOUNT_SID'], $_ENV['TWILIO_AUTH_TOKEN']);

$container->set(Client::class, fn(): Client => $client);
if (session_status() !== PHP_SESSION_ACTIVE) {
    session_start();
}

$flash = new Messages($_SESSION);
$container->set('flash', fn(): Messages => $flash);

$container->set(
    LoggerInterface::class,
    fn(): LoggerInterface => new Logger('name')
        ->pushHandler(
            new StreamHandler(__DIR__ . '/../data/app.log', Level::Warning),
        ),
);

AppFactory::setContainer($container);
$app = AppFactory::createFromContainer($container);
$app->add(
    TwigMiddleware::create(
        $app,
        Twig::create(__DIR__ . '/../src/templates', ['cache' => false]),
    ),
);
$application = new Application(
    $app,
    $client,
    $flash,
    new Logger('name')
        ->pushHandler(
            new StreamHandler(__DIR__ . '/../data/app.log', Level::Info),
        ),
);
$application->setupRoutes();
$application->run();

The code initialises a new Slim Framework object, and passes that to a new Application object; which contains all of the functionality for handling requests to the application's various routes. The Application object is also initialised with a Twilio Rest Client object for making requests to Twilio's APIs, a Slim Flash Messages app for flashing information between requests, and a Monolog Logger object for application instrumentation; writing log data to data/app.log.

Then, replace the existing code in src/Application.php with the following:

<?php

declare(strict_types=1);

namespace App;

use Fig\Http\Message\StatusCodeInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Log\LoggerInterface;
use Slim\App as SlimApp;
use Slim\Flash\Messages;
use Slim\Interfaces\RouteInterface;
use Slim\Middleware\ContentLengthMiddleware;
use Slim\Views\Twig;
use Twilio\Rest\Client;

use function in_array;
use function sprintf;

/**
 * This class encapsulates the central Slim application,
 * making it easier to create and test.
 */
final class Application
{
    /**
     * @var array{'label'?: string, 'detail'?: string, 'passed'?: string}
     */
    private array $steps = [];

    public function __construct(
        private readonly SlimApp $app,
        private readonly Client $client,
        private readonly Messages $flash,
        private readonly LoggerInterface $logger,
    ) {
        $app->add(new ContentLengthMiddleware());
        $app->addBodyParsingMiddleware();
        $app->addRoutingMiddleware();
        $app->addErrorMiddleware(true, true, true);
    }

    /**
     * setupRoutes sets up the application's routing table
     */
    public function setupRoutes(): void
    {
        $this->app->map(['GET', 'POST'], '/', [$this, 'handleSignupStage']);
        $this->app->map(['GET', 'POST'], '/verify', [$this, 'handleVerifyStage']);
        $this->app->get('/status', [$this, 'handleUserStatus']);
    }

    /**
     * getRoutes returns the application's current routes
     *
     * @return RouteInterface[]
     */
    public function getRoutes(): array
    {
        return $this->app->getRouteCollector()->getRoutes();
    }

    /**
     * Launches the application
     */
    public function run(): void
    {
        $this->app->run();
    }

    /**
     * Displays or processes the sign-up form
     */
    public function handleSignupStage(
        ServerRequestInterface $request,
        ResponseInterface $response,
    ): ResponseInterface {
        if ($request->getMethod() === "POST") {
            $requestData = $request->getParsedBody();
            $phoneNumber = $requestData['phone'] ?? '';
            $firstName   = $requestData['firstName'] ?? '';
            $lastName    = $requestData['lastName'] ?? '';

            if ($phoneNumber === "" || $firstName === '' || $lastName === '') {
                $this->logger->error("Sign-up form error. Missing data.");
                return $response
                    ->withHeader("Location", "/")
                    ->withStatus(StatusCodeInterface::STATUS_FOUND);
            }

            $status = $this->runOnboardingIntelligence($phoneNumber, $firstName, $lastName);
            if (! $status['ok']) {
                $this->flash->addMessage('reason', $status['reason']);
                return $response
                    ->withHeader("Location", "/status")
                    ->withStatus(StatusCodeInterface::STATUS_FOUND);
            }

            $this->client
                ->verify
                ->v2
                ->services($_ENV['TWILIO_VERIFY_SERVICE_SID'])
                ->verifications->create($phoneNumber, "sms");

            $this->logger->info(sprintf("Sending OTP to: %s", $phoneNumber));

            $this->flash->addMessage('phone', $phoneNumber);

            return $response
                ->withHeader("Location", "/verify")
                ->withStatus(StatusCodeInterface::STATUS_FOUND);
        }

        return Twig::fromRequest($request)
            ->render(
                $response,
                'signup.html.twig',
                [],
            );
    }

    /**
     * @return array{'ok': bool, 'reason': string, 'steps'?: array<int,string|bool>}
     */
    private function runOnboardingIntelligence(string $phoneNumber, string $firstName, string $lastName): array
    {
        $numberDetails = $this->client
            ->lookups
            ->v2
            ->phoneNumbers($phoneNumber)
            ->fetch(
                [
                    "fields"    => "line_type_intelligence,line_status,identity_match",
                    "firstName" => $firstName,
                    "lastName"  => $lastName,
                ],
            );

        if ($numberDetails->lineTypeIntelligence['type'] !== "mobile") {
            $this->flash->addMessage('status', 'rejected');
            $this->logSteps("Line Type Intelligence", $numberDetails->lineTypeIntelligence['type'], false);
            return [
                'ok'     => false,
                'reason' => 'LINE_TYPE_BLOCKED',
                'steps'  => $this->steps,
            ];
        }
        $this->logSteps("Line Type Intelligence", $numberDetails->lineTypeIntelligence['type'], true);

        $identityMatchEnabled = $_ENV['IDENTITY_MATCH_ENABLED'] ?? "false";
        if ($identityMatchEnabled === "true") {
            $firstNameMatch = $numberDetails->identityMatch['first_name_match'] ?? '';
            $lastNameMatch  = $numberDetails->identityMatch['last_name_match'] ?? '';
            if (
                ! in_array($firstNameMatch, ['exact_match', 'high_partial_match'])
                    || ! in_array($lastNameMatch, ['exact_match', 'high_partial_match'])
            ) {
                $this->flash->addMessage('status', 'rejected');
                $this->logSteps("Identity Match", sprintf("first: %s, last: %s", $firstNameMatch, $lastNameMatch), false);
                return [
                    'ok'     => false,
                    'reason' => 'IDENTITY_MATCH_UNAVAILABLE',
                    'steps'  => $this->steps,
                ];
            }
            $this->logSteps("Identity Match", sprintf("first: %s, last: %s", $firstNameMatch, $lastNameMatch), true);
        }

        $lineStatusEnabled = $_ENV['LINE_STATUS_ENABLED'] ?? "false";
        if (
            $lineStatusEnabled === "true"
                && in_array($numberDetails->lineStatus['Status'], ["Inactive", "Unreachable"])
        ) {
            $this->flash->addMessage('status', 'rejected');
            $this->logSteps("Line Status", $numberDetails->lineStatus['Status'], false);
            return [
                'ok'     => false,
                'reason' => 'LINE_STATUS_BLOCKED',
                'steps'  => $this->steps,
            ];
        }

        $this->flash->addMessage('status', 'approved');
        return [
            'ok'    => true,
            'steps' => $this->steps,
        ];
    }

    private function logSteps(string $label, string $detail, bool $passed): void
    {
        $this->steps[] = [$label, $detail, $passed];
        $this->logger->info(
            "Step " . $passed ? "Passed" : "Failed",
            [
                sprintf('%s:%s', $label, $detail),
            ],
        );
    }

    /**
     * Displays or processes the verification form
     */
    public function handleVerifyStage(
        ServerRequestInterface $request,
        ResponseInterface $response,
    ): ResponseInterface {
        if ($request->getMethod() === "POST") {
            $requestData = $request->getParsedBody();
            $code        = $requestData['code'] ?? '';
            $phoneNumber = $requestData['phone'] ?? '';

            if ($code === '' || $phoneNumber === '') {
                $this->logger->info("HandleVerifyStage", [
                    'Error'   => 'Form Processing Error',
                    'Details' => 'Either the code or phone number were missing or invalid',
                ]);

                $this->flash->addMessage('phone', $phoneNumber);

                return $response
                    ->withHeader("Location", "/verify")
                    ->withStatus(StatusCodeInterface::STATUS_FOUND);
            }

            $result = $this->client
                ->verify
                ->v2
                ->services($_ENV['TWILIO_VERIFY_SERVICE_SID'])
                ->verificationChecks
                ->create([
                    "code" => $code,
                    "to"   => $phoneNumber,
                ]);

            $this->flash->addMessage('status', $result->status === 'approved' ? 'approved' : 'rejected');

            return $response
                ->withHeader("Location", "/status")
                ->withStatus(StatusCodeInterface::STATUS_FOUND);
        }

        return Twig::fromRequest($request)
            ->render($response, 'verify.html.twig', [
                'phoneNumber' => $this->flash->getFirstMessage('phone'),
            ]);
    }

    /**
     * Displays user status information
     */
    public function handleUserStatus(
        ServerRequestInterface $request,
        ResponseInterface $response,
    ): ResponseInterface {
        return Twig::fromRequest($request)
            ->render($response, 'status.html.twig', [
                'status' => $this->flash->getFirstMessage('status'),
                'reason' => $this->flash->getFirstMessage('reason') ?? '',
            ]);
    }
}

The Application object's constructor adds the ability to parse JSON request bodies, as that is how Twilio packages request and response information, it loads the application's routing table (defined in setupRoutes()), and it adds error middleware for handling fatal errors and exceptions.

The setupRoutes() function defines three routes:

The default route (/) which is handled by the handleSignupStage() function, accessible with GET and POST requests.
The verify route (/verify) which is handled by the handleVerifyStage() function, accessible with GET and POST requests.
The status route (/status) which is handled by the handleUserStatus() function, accessible with GET requests.

The handleSignupStage() function renders and returns src/templates/signup.html.twig if requested with the GET method. It is a simplistic form for collecting a user's phone number, first name, and last name.

If requested with the POST method, it will retrieve the phone, firstName, and lastName attributes from the request's POST data, redirecting the user to the default route if one or more of those attributes are not present or empty.

Otherwise, it will call runOnboardingIntelligence(), which we'll discuss shortly, to retrieve and validate details about the supplied phone number. If the phone number is marked as invalid, indicated by the ok element of the array returned from that function being set to false, a flash message named reason is created with the value in the reason element of the returned array, before the user is redirected to the /status route, where that information will be shown to the user.

If the phone number is marked as valid, the user will be sent an OTP code via SMS and a flash message named phone will be created with the submitted phone number, before they're redirected to the /verify route, where they can verify the OTP code that they were sent.

Now, let's step through runOnboardingIntelligence(). This function attempts to retrieve Line Type Intelligence, Line Status, and Identity Match information on the supplied phone number, using the provided first and last name.

If the phone number's type is not set to "mobile", then a flash message named status is set to "rejected", logSteps() is called to record that the Line Type Intelligence check failed, before returning an array with ok set to false, the reason for the rejection, and the check step that were completed.

If IDENTITY_MATCH_ENABLED is enabled, then that information in the returned lookup data is checked to see if either the first and/or last names were either an exact or high partial match for the phone number owner's first and last names. If not, similar to the previous, Line Type Intelligence check, a flash message named status is set to "rejected", logSteps() is called to record that the Identity Match check failed, before returning an array with ok set to false, the reason for the rejection, and the check step that was completed. If the check succeeded, then the step is logged as being successful.

Finally, if LINE_STATUS_ENABLED is enabled, then the phone number's status is checked. If it's set to either "Inactive" or "Unreachable", a flash message named status is set to "rejected", logSteps() is called to record that the Line Status check failed, before returning an array with ok set to false, the reason for the rejection, and the check step that was completed. If the check succeeded, then the step is logged as being successful.

If the respective checks all passed, a flash message named status is marked as "approved", and the returned array sets ok to true and contains the logged (checked) steps.

The handleVerifyStage() function renders src/templates/verify.html.twig with the value of the phone flash message if the request method was GET. If the request method was POST, the code and phone number are retrieved from the submitted POST request data. If either of them are not available or empty, that fact is logged before the user is redirected to the "/verify" route to try and validate the received code again.

Otherwise, the Twilio Rest Client is used to verify the supplied code. If the status is set to "approved", then a flash message named "status" is set to "approved" or "rejected" based on whether the result's status field is set to "approved" or not. After that, the user is redirected to the "/status" route.

The handleUserStatus() function renders src/templates/status.html.twig with two template variables:

status: This is set to the value of the status flash message
reason: This is set to the value of the reason flash message

Now, create a new file called src/templates/base.html.twig and paste the code below into the new file.

<!doctype html>
<html lang="en-AU">
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>{% block title %}{% endblock %}</title>
    <link href="/css/styles.css" rel="stylesheet">
</head>
<body class="container">
    <main>
        <h1>{% block h1 %}{% endblock %}</h1>
        {% block content %}{% endblock %}
    </main>
</body>
</html>

This is the base template, which the remaining three will build upon. It contains the elements central to all the others, ensuring that the remaining ones contain only details pertinent to that specific template.

Then, create a new file called src/templates/signup.html.twig which will render a very basic UI to collect a phone number, first name, and last name, and paste the code below into the file.

{% extends 'base.html.twig' %}

{% block title %}Sign up{% endblock %}
{% block h1 %}Sign up{% endblock %}
{% block content %}
<form action="/" enctype="application/x-www-form-urlencoded" id="signup-form" method="POST">
    <label>Phone: <input inputmode="tel" name="phone" required type="tel" /></label>
    <label>First name: <input name="firstName" required /></label>
    <label>Last name: <input name="lastName" required /></label>
    <button class="primary" type="submit">Submit</button>
</form>
{% endblock %}

Then, create a new file called src/templates/verify.html.twig which will render a simple form for validating the OTP code received by the user, and paste the code below into the new file.

{% extends 'base.html.twig' %}

{% block title %}Enter OTP{% endblock %}
{% block h1 %}Enter OTP{% endblock %}
{% block content %}
    <ul>
        {% for check in checks %}
        <li>{{ check.passed ? '✅' : '❌' }} <strong>{{ check.label }}:</strong> <code>{{ check.detail }}</code></li>
        {% endfor %}
    </ul>
    {% if codeSent %}
    <p>We sent a code to <code>{{ phoneNumber }}</code>.</p>
    {% endif %}
    <form
        action="/verify"
        enctype="application/x-www-form-urlencoded"
        method="POST"
    >
        <label>
            Code:
            <input name="code" required pattern="\d{6}" minlength="6" maxlength="6" inputmode="numeric" />
        </label>
        <button class="primary" type="submit">Verify</button>
        <input type="hidden" name="phone" value="{{ phoneNumber }}" />
    </form>
    <p><a href="/">Back</a></p>
{% endblock %}

Finally, create a new file called src/templates/status.html.twig, which will show whether the phone details and OTP code verification were successful or not:

{% extends 'base.html.twig' %}

{% block title %}{{ title }}{% endblock %}
{% block h1 %}{{ status|title }}{% endblock %}
{% block content %}
{% if status == 'rejected' %}
<p>Reason: <code>{{ reason|default('') }}</code></p>
<p><a href="/">Back</a></p>
{% endif %}
{% endblock %}

Run and test the code

Save your files and run the project with:

composer serve

Open http://localhost:3000 and test it out with your personal mobile number. Now, you should see log records in data/app.log similar to the following:

[2026-08-28T04:50:18.538245+00:00] name.INFO: Passed ["Line Type Intelligence:mobile"] []
[2026-08-28T05:03:57.081471+00:00] name.INFO: Sending OTP to: +61493856711 [] []

At this point you may get Error 60619: Lookup Request Cannot be Completed in Twilio Region. Learn more about availability by country and request access here. Alternatively, you can use our sandbox experience with test credentials and magic numbers.

You can also test with a toll free or VoIP number like +17739857836 and you'll see an error with LINE_TYPE_BLOCKED. Or use your real phone number but with a different name and see Identity Match fail. Testing all possible outcomes of line status and identity match is a little tricker, so we recommend using test credentials and magic numbers.

Pricing considerations and next steps

One of the reasons this is 4 different API calls is that we want to be considerate of price. Line Type Intelligence and Line Status are the cheapest Lookup packages, while Identity Match and Verify are more expensive. Learn more about Lookup pricing (varies by country) and rearrange the steps to fit your use case.

Bundling Lookup and Verify is a great way to filter out unwanted bots, fake accounts, and reduce sign up fraud. It also allows you to validate real users seamlessly. For more information, check out:

I can't wait to see what you build and secure.

Matthew Setter is a PHP, Go, and Rust Editor in the Twilio Voices team. He’s also the author of Mezzio Essentials and Deploy with Docker Compose. You can find him at msetter@twilio.com. He's also on LinkedIn and GitHub.

Related Resources

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.

How to Approve Real Users and Block Fake Accounts at Sign Up with Lookup and Verify in PHP

Related Posts

Related Resources