Skip to main content
API docs by Redocly

Veriph.One's API (1.X.X)

Download OpenAPI specification:Download

This is the documentation for Veriph.One's integration and service APIs. You can find more information about our company at www.veriph.one.

Introduction

This API in grouped into specific categories based on common platform use-cases; for example:

  • The SDK Integration group is used to make a complete integration with our platform and use all of our verification methods insided your mobile and web apps. This is the most common use case.
  • The Helper Services group aggregates endpoints used for more complex interactions with our platforms where you want to go beyond our SDK's functionality.
  • Lastly, the Misc category is used to interact and monitor our infrastructure.

OpenAPI Specification

This API is documented in OpenAPI format and can also be explored using Swagger via its standalone website, or its JSON and YAML definitions.

Authentication

The endpoints shown here are offered under API-Key-based authentication. Please consider that some endpoints require only your API Key, while others need your Secret as well. Keep your credentials safe and never include them in your code repositories as plain text. Also, don't expose your API Secret to client-side code, as it can be stolen.

Versioning

Our versioning strategy goes beyond a global API version, and we follow a pattern where endpoints have individual versions instead of the API as a whole. This allows for more versatility and better backwards compatibility. Please consider that only major versions (e.g., v1.X.X or v2.X.X) will be incompatible to endpoints with previous versions.

1. SDK Integration

Start a verification session

Create a verification session for the SDK using the configuration of the API Key provide as credentials. It can be further customized by passing the optional configuration parameter. Please ensure that the metadata object is correctly filled as it is used to configure the user experience and detect fraud. Additionally, if you pass an object to the optional prefilledPhoneNumber, you can set up a 2FA/MFA flow or one where the user will need to verify a specific number; this interacts prefilledPhoneNumber.userCanEdit to allow them to change the number to be verified.

header Parameters
x-api-key
required
string

Your Veriph.One API Key

Request Body schema: application/json
required
object

This object determines whether the verification process will capture an unknown number or do a 2FA/MFA flow with a known one. In case of the latter, the verification will be rejected if the user verifies a different number.

required
object

Necessary data to detect bots, unique transactions, fraudsters, and user's approximate location.

object

Used to setup the verification process based on context provided by your application.

Responses

Request samples

Content type
application/json
{
  • "prefilledPhoneNumber": {
    },
  • "metadata": {
    },
  • "configuration": {
    }
}

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "redirectionUrl": "string"
}

Get verification result (v1.0.0)

Obtain the results of a verification using a session UUID and your API Key credentials. This endpoint should never be called from client-side software to avoid leaking your API Key.

query Parameters
sessionUuid
required
string
header Parameters
authorization
required
string

Your Veriph.One API Key Secret; using the Basic auth structure: Basic XXXX...XXXX

x-api-key
required
string

Your Veriph.One API Key

Responses

Response samples

Content type
application/json
{
  • "prefilledCountryCode": "string",
  • "prefilledPhoneNumber": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "closedAt": "2019-08-24T14:15:22Z",
  • "userId": "string",
  • "firstSuccessfulAttempt": {
    },
  • "attempts": [
    ]
}

Get verification result (v1.1.0)

Obtain the results of a verification using a session UUID and your API Key credentials. This endpoint should never be called from client-side software to avoid leaking your API Key. Version 1.1.0 also includes data enrichment objects that contain information on the phone number that was verified and the context of the verification process. These data points are optional and can be ommitted to reduce latency.

query Parameters
sessionUuid
required
string
enrichmentType
required
number
Default: 0

Determines the type of enrichment you want to obtain. Take into consideration that if you request all of the data points, the payload will increase in size substantially and latency might be introduced. We recommend only getting the data points you need based on the context around the verification. By default, no enrichment is done. See catalog of possible values here.

header Parameters
authorization
required
string

Your Veriph.One API Key Secret; using the Basic auth structure: Basic XXXX...XXXX

x-api-key
required
string

Your Veriph.One API Key

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "closedAt": "2019-08-24T14:15:22Z",
  • "initialConfiguration": {
    },
  • "type": "string",
  • "result": {
    },
  • "verificationMetadata": {
    }
}

2. Helper Services

Get phone country codes

Obtain the full list of country codes including ISO 3166-2 codes.

header Parameters
x-api-key
required
string

Your Veriph.One API Key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Send a non-SDK OTP

This endpoint is a standalone service that allows your application to send OTP messages via SMS, WhatsApp (requires initial setup; contact us for more information), and phone call without using the Veriph.One SDK. Please note that this service has an independent billing scheme (per message sent not successful verification), and by using it you are losing SMS pumping protection and other important security features.

header Parameters
authorization
required
string

Your Veriph.One API Key Secret; using the Basic auth structure: Basic XXXX...XXXX

x-api-key
required
string

Your Veriph.One API Key

Request Body schema: application/json
required
countryCode
required
string

Expected number's country code, without '+' sign or non-numeric characters

cellphoneNumber
required
string

Expected phone number without country code or non-numeric characters

channel
required
number

The channel to use for the message. Values: SMS [0], WhatsApp [1], Phone Call [2].

otpCode
required
string

The OTP to include in the message template. Enforced string length range: 4-16. Only alphanumeric characters accepted (no diacritics, whitespace or symbols): 0-9, a-z, and A-Z.

brandLabel
required
string

A string to let user know who is sending the OTP, use a short brand/product name; must be at least 2 characters long. The string might be shortened if space is needed to fit the message inside a single SMS message. The string is shown inside parentheses for SMS/WhatsApp; for example, in english: ({brandLabel}) Your verification code is ${otpCode}. Do not share it with others. For phone calls, the structure is as follows: Your verification code for ${brandLabel} is ${otpCode}. Do not share it with others..

locale
required
string
Default: "en"

String determining the language of the message to be sent in ISO 639-1 format. Currently, only en and es are supported.

userAgent
required
string or null

Used to detect fraudsters, bots, and identity theft; please ensure that you are sending proper values as obtained by your server.

ipAddress
required
string or null

The user's IP address captured by your server. This is a critical data point to detect fraud, offer the best verification methods available, among other operations.

Responses

Request samples

Content type
application/json
{
  • "countryCode": "string",
  • "cellphoneNumber": "string",
  • "channel": 0,
  • "otpCode": "string",
  • "brandLabel": "string",
  • "locale": "en",
  • "userAgent": "string",
  • "ipAddress": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "countryCode": "string",
  • "phoneNumber": "string",
  • "channel": 0,
  • "locale": "string",
  • "referenceId": "string"
}

3. Misc Endpoints

Health Check

Simple endpoint to check on our servers' availability.

Responses

Response samples

Content type
application/json
{
  • "module": "string",
  • "now": "string"
}