Start Endpoint

The Veriph.One SDK can handle three use cases for you:

1. Secure and fraud-proof capture of a user's phone number during sign-up, onboarding, or KYC. Our Demo app showcases this flow.
2. The validation of sensitive transactions through Multi-Factor Authentication (MFA/2FA) using a phone number linked to the current user.
3. Let users verify previously captured yet unverified phone numbers.

To start these verification flows, you must create a Start Endpoint in your server that your mobile or web app can trigger. This endpoint will connect to our API and request the verification to start based on your configuration parameters.

tip

Unless your business logic is too complex, these flows can coexist within the same endpoint. Feel free to create unique Start Endpoints for each use case, but always remember to create their counterpart Result Endpoints.

Step 1: Create the Endpoint

Start by creating a new web service on your server that your web and mobile apps can access. This endpoint must capture the user's IP address, locale (if applicable), and user agent string to build the metadata object needed to create a session and detect fraud. Follow the specifications below based on the architecture you chose in the previous step.

note

When following our recommended architecture for a mixed implementation with platform-specific endpoints, create your endpoints based on the mobile-only and web-only specifications.

Specification

api.example.com/verification-start

• Web-Only
• Mobile-Only
• Mixed (Reusable)

Method

GET

Headers

Name	Required	Type	Description
User-Agent	Yes	String	Used to build the metadata object you'll need later on.

Responses

Code	Location	Notes
307	The URL returned in step 2.	To be returned if verification session was created successfully.
307	An URL on your app that can handle an error state.	In case the verification session wasn't created and an eror needs displaying.

Notes

The endpoint needs to be publicly accessible since the request will be coming from your user's browser. Most importantly, from the user's perspective, this endpoint must behave as a webpage that is trying to load but instead redirects to the verification flow.

Step 2: Create a Session

Once you build your Start Endpoint, connect to Veriph.One's create-session web service to create a session and obtain its UUID (used for mobile) and redirection URL (used for web apps). Once you have it, you can store the session UUID in your database and link it to your user's transaction. Storing it will be helpful when you are notified of the result through that same UUID when the process finishes.

Moreover, you'll need to create a couple of objects sent as part of the request's payload to create a session. These include a metadata object containing elements that help counteract fraud and impersonation, a session configuration object with preferences on how to show the UI to your user, and a prefilled phone number in case you are working with an MFA/2FA use case.

This same create-session web service supports all three previously described use cases based on how you build the request's payload.

The Metadata Object

The metadata object is relevant to detect suspicious behavior across the verification lifecycle and interactions with specific phone numbers. It's one of our tools for combating fraud targeting your app.

Additionally, it captures a user ID that doesn't need to be identical to the one you use in your software; if you wish, you can hash it to distort its original nature. The most relevant part of the user ID is that we use it to detect users who are trying to access other's accounts or using a multitude of phone numbers at the same time; as such, it's critical that users don't share IDs between them and that a same user doesn't have more than one assigned.

tip

Avoid sending personally identifiable information as part of the metadata object. Even though our database is secure and doesn't expose this information, using personal data like names, emails, contact information, document ID numbers, or similar can become a privacy issue. Always send UUIDs, unidentifiable numbers, hashes, or masked data.

Prefilling Numbers for MFA/2FA

Suppose your software employs Veriph.One for the MFA/2FA use case. In that case, you'll need to start a session with a prefilled phone number, which means that the user won't be able to edit or change the number used for the process.

Conversely, if you don't prefill this object, your users can capture any number and do the verification process with it. B2C products commonly use this scenario in registration forms, onboarding, KYC, and cases where the number is unknown, and you want to ensure that it's an actual number in the user's possession.

Finally, you can prefill the number and allow users to change it during verification using the userCanEdit field on the PrefilledPhoneNumber object. This scenario is helpful for use case three (from the list at the top of the page), where you want to capture unverified numbers first and then let the user go through verification without soft-locking them because of a typo.

Step 3: Verification Kick-Off

Once you have successfully created a verification session and stored its UUID on your database, it is time to take your user through the verification flow. As you saw on the Start Endpoint specification, this kick-off will depend on the platform you are working with. Once you finish implementing this service, move on to the last part of the tutorial: the Result Endpoint.

Web

Since a browser will hit your Start Endpoint, your user will wait for all the steps described on this page to complete. As such, try to make this endpoint as quick as possible to create the best possible experience.

The final step is to use the redirectionUrl property returned by the create-session endpoint to make your Start Endpoint return an HTTP code 307 and redirect to it. Veriph.One will then show the verification UI to your user, displaying the default style if you have yet to customize it.

warning

If your server needs to return an error, avoid responding with anything different than the HTTP code 307. If you do, the browser won't render the website, leaving your user with little to no information on what happened. The best way to handle this is to redirect to your web app with sufficient data to render the error or decide what to do next.

Mobile

If everything goes well, your server must return a payload that your mobile apps can parse to obtain the session UUID. With it, they can trigger our SDK to start the verification flow.

Otherwise, your server can also return an error based on the issue encountered when creating a verification session.