API Reference
Base URL: https://service.veriph.one
tip
Swagger fan? Are you curious about how to tinker with our API? We've got you covered! Access our Swagger API specification here:
Create Session
POST /sdk-api/phone-verification/create-session/v1.0.0
Headers
| Name | Required | Value/Description |
|---|---|---|
| x-api-key | Yes | A string containing your API Key, get yours at dashboard.veriph.one |
| Content-Type | Yes | application/json |
Parameters
Encoded as a JSON object in the request body.
| Name | Required | Type | Description |
|---|---|---|---|
| metadata | Yes | SessionMetadata | Data used to detect anomalous behavior |
| configuration | No | SessionConfiguration | Optional field to customize flow |
| prefilledPhoneNumber | No | PrefilledPhoneNumber | If sent, the flow will have 2FA behavior, and the user won't be able to input a new phone number. Don't send it if you want to capture the user's phone number. |
Responses
| Code | Content-type | Response Body | Notes |
|---|---|---|---|
200 | application/json | SessionCreationResponse | Successful request |
400 | application/json | ErrorMessage | Incomplete or invalid inputs |
5XX | None | None | Server is down. |
Verification Result
GET /sdk-api/phone-verification/verification-result/v1.0.0
Headers
| Name | Required | Value/Description |
|---|---|---|
| x-api-key | Yes | A string containing your API Key, get yours at dashboard.veriph.one |
| Authorization | Yes | String containing your API Key secret in the format Basic [YOUR API KEY SECRET] |
| Content-Type | Yes | application/json |
Parameters
Appended to the URL as query params.
| Name | Required | Type | Description |
|---|---|---|---|
| sessionUuid | Yes | String | The uuid of the session created using the create-session endpoint |
Responses
| Code | Content-type | Response Body | Notes |
|---|---|---|---|
201 | application/json | VerificationResult | Successful request |
400 | application/json | ErrorMessage | Incomplete or invalid inputs |
5XX | None | None | Server is down. |
Objects
ErrorMessage
| Property | Description | Type | Optional |
|---|---|---|---|
| errorMessage | Developer friendly error message in english. | String | Yes |
| internalErrorCode | Non-http-code that facilitates debugging. | Number | No |
Internal Error Codes
| Code | Description |
|---|---|
| 14226 | Session creation request missing metadata object or fields are incomplete. |
| 20000 | Country code is invalid or has unknown format. |
| 20001 | Phone number is invalid or has unknown format. |
SessionMetadata
| Property | Description | Type | Nullable | Required |
|---|---|---|---|---|
| userId | String containing a unique identifier for the user making the operation. | String | No | Yes |
| ipAddress | String containing the user's IP address at the time of the verification. | String | No | Yes |
| userAgent | String containing the user's user agent at the time of the verification. | String | No | No |
tip
We encourage you to send as much information as possible through this object with maximum fidelity; we use these fields to protect your application from fraud and suspicious transactions. However, we don't need any information that identifies the user personally, so try to avoid doing so.
PrefilledPhoneNumber
| Property | Description | Type | Nullable | Required |
|---|---|---|---|---|
| countryCode | Digit-only string containing the user's country code without the '+' sign. | String | No | Yes |
| cellphoneNumber | Digit-only string containing the user's phone number without country code. | String | No | Yes |
| userCanEdit | Allows user to edit the phone provider by your server. | Boolean | No | No |
SessionConfiguration
| Property | Description | Type | Nullable | Required |
|---|---|---|---|---|
| locale | String determining the language to be shown to the user in the UI in ISO 639-1 format. | String | No | Yes |
| enforceInput | Force users to manually enter their phone number before initiating Inverse OTP verification. | Boolean | No | No |
tip
The user interface is shown in English by default when the locale is unspecified. However, the user can change the language at any time using a language selector.
SessionCreationResponse
| Property | Description | Type | Nullable |
|---|---|---|---|
| uuid | String containing the UUID of the session created. | String | No |
| createdAt | String containing the session's creation date in ISO8601 format. | String | No |
| redirectionUrl | URL used to redirect the user to the intented verification flow. | String | No |
Attempt
| Property | Description | Type | Nullable |
|---|---|---|---|
| uuid | The attempt's unique ID. | String | No |
| createdAt | The attempt's creation date time in ISO8601 format. | String | No |
| countryCodeInput | Country code selected by the user. | String | No |
| phoneNumberInput | Phone number submitted by the user. | String | No |
| method | Verification method used. Possible values. | Number | No |
| status | Verification attempt's current state. Status catalog | Number | No |
Verification Method Types
| Code | Description |
|---|---|
| 10 | Inverse OTP via SMS. |
| 11 | Inverse OTP via WhatsApp. |
| 20 | Traditional OTP via SMS. |
| 21 | Traditional OTP via WhatsApp. |
| 30 | Traditional OTP via Robocall. |
Attempt Statuses
| Code | Description |
|---|---|
| 0b00000000000000 | Waiting for verification. |
| 0b10000000000000 | Verification successful. |
| 0b01000000000001 | Destination mismatch. For Inverse OTP, means someone tried to tamper with the result. |
| 0b01000000000010 | Origin mismatch. For Inverse OTP, user sent the message from a different number. |
| 0b01000000000100 | Attempt status was invalided because the session closed. |
| 0b01000000001000 | Attempt expired. |
| 0b01000000010000 | Client was disabled due to pending payment or administrative reasons. |
| 0b01000000100000 | Potential tampering due to mismatching verification methods. |
| 0b01000001000000 | Too many Traditional OTP submissions. |
| 0b01000010000000 | User exceeded their Traditional OTP quota for the current method. |
| 0b01000100000000 | Attempt made invalid by user-triggered cancellation/request. |
tip
As you can see, Veriph.One uses binary flags to determine the status of each attempt. These statuses can overlap, and you could have cases where verification is successful, but later, someone tried to tamper with it. The statuses can update over time due to this reason. We recommend masking the status result using an AND operation if you want to check for a specific status.
VerificationResult
| Property | Description | Type | Nullable |
|---|---|---|---|
| prefilledCountryCode | Prefilled code sent to create-session | String | Yes |
| prefilledPhoneNumber | Prefilled number sent to create-session | String | Yes |
| createdAt | Session's creation date time in ISO8601 format. | String | No |
| closedAt | Session's closure date time in ISO8601 format. | String | No |
| userId | Metadata sent to create-session | String | Yes |
| firstSuccessfulAttempt | The successful verification result, if any. | Attempt | Yes |
| attempts | Array of attempts made by user. | Attempt[] | No |