Download OpenAPI specification:Download

Verifications

Start new verification requests and report on existing verification requests.

Start verification

This method is used by the mobile and web Verification SDKs to start a verification. It can also be used to request a verification from your backend, by making an request.

SecurityBasic
Request
Request Body schema: application/json
required
object (Identity)

Specifies the type of endpoint that will be verified and the particular endpoint. number is currently the only supported endpoint type.

method
required
string (VerificationMethod)

The type of the verification request.

Enum: Description
sms

Verification by SMS message with a PIN code.

flashCall

Verification by placing a flashcall (missed call) and detecting the incoming calling number (CLI).

callout

Verification by placing a PSTN call to the user's phone and playing an announcement, asking the user to press a particular digit to verify the phone number (only iOS).

seamless

Data verification. Verification by accessing internal infrastructure of mobile carriers to verify if given verification attempt was originated from device with matching phone number.

reference
string

Used to pass your own reference in the request for tracking purposes.

custom
string

Can be used to pass custom data in the request.

object

An optional object for flashCall verifications. It allows you to specify dial time out parameter for flashCall. FlashCallOptions object can be specified optionally, and only if the verification request was triggered from your backend (no SDK client) through an Application signed request.

Responses
200

A successful response.

Response Schema: application/json
One of:
id
string

Verification identifier used to query for status.

method
string
Default: "sms"

The value of the method used for the Verification. For SMS Verifications, this will always be sms.

object

The response contains the template of the SMS to be expected and intercepted.

object (_linksObject)

Available methods and actions which can be done after a successful Verification

400

INVALID_ARGUMENT

post/verification/v1/verifications
Request samples
application/json
{
  • "identity": {
    • "type": "number",
    • "endpoint": "+46700000000"
    },
  • "method": "sms"
}
Response samples
application/json
{
  • "id": "1234567890",
  • "method": "sms",
  • "sms": {
    • "template": "Your verification code is {{CODE}}",
    • "interceptionTimeout": 32
    },
  • "_links": {
    • "rel": "status",
    • "href": "string",
    • "method": "GET"
    }
}

Report a verification using Identity

Report the received verification code to verify it, using the identity of the user (in most cases, the phone number). For an SMS PIN verification or callout verification, this is the OTP code. For flashcalls, this is the CLI.

SecurityBasic
Request
path Parameters
endpoint
required
string

For type number use a E.164-compatible phone number.

Request Body schema: application/json
One of:
method
required
string

The type of verification.

required
object

A configuration object containing settings specific to SMS verifications.

Responses
200

A successful response.

Response Schema: application/json
One of:
id
string

The unique ID of the verification request.

method
string

The method of the verification request. This will always be sms.

status
string

The status of the verification request.

Enum: Description
PENDING

The verification is ongoing.

SUCCESSFUL

The verification was successful.

FAIL

The verification attempt was made, but the number wasn't verified.

DENIED

The verification attempt was denied by Sinch or your backend.

ABORTED

The verification attempt was aborted by requesting a new verification.

ERROR

The verification couldn't be completed due to a network error or the number being unreachable.

reason
string

Displays the reason why a verification has FAILED, was DENIED, or was ABORTED.

Enum: "“Fraud”" "Not enough credit" "Blocked" "Denied by callback" "Invalid callback" "Internal error" "Destination denied" "Network error or number unreachable" "Failed pending" "SMS delivery failure" "Invalid CLI" "Invalid code" "Expired" "Hung up without entering valid code"
reference
string

The reference ID that was optionally passed together with the verification request.

source
string

Free text that the client is sending, used to show if the call/SMS was intercepted or not.

Enum: "intercepted" "manual"
400

INVALID_ARGUMENT

put/verification/v1/verifications/number/{endpoint}
Request samples
application/json
{
  • "method": "sms",
  • "sms": {
    • "code": "123"
    }
}
Response samples
application/json
{
  • "id": "1234567890",
  • "method": "string",
  • "status": "FAIL",
  • "reason": "“Fraud”",
  • "reference": "12345",
  • "source": "intercept"
}

Report a verification with ID

Report the received verification code to verify it, using the Verification ID of the Verification request.

SecurityBasic
Request
path Parameters
id
required
string
Request Body schema: application/json
One of:
method
required
string

The type of verification.

required
object

A configuration object containing settings specific to SMS verifications.

Responses
200
Response Schema: application/json
One of:
id
string

The unique ID of the verification request.

method
string

The method of the verification request. This will always be sms.

status
string

The status of the verification request.

Enum: Description
PENDING

The verification is ongoing.

SUCCESSFUL

The verification was successful.

FAIL

The verification attempt was made, but the number wasn't verified.

DENIED

The verification attempt was denied by Sinch or your backend.

ABORTED

The verification attempt was aborted by requesting a new verification.

ERROR

The verification couldn't be completed due to a network error or the number being unreachable.

reason
string

Displays the reason why a verification has FAILED, was DENIED, or was ABORTED.

Enum: "“Fraud”" "Not enough credit" "Blocked" "Denied by callback" "Invalid callback" "Internal error" "Destination denied" "Network error or number unreachable" "Failed pending" "SMS delivery failure" "Invalid CLI" "Invalid code" "Expired" "Hung up without entering valid code"
reference
string

The reference ID that was optionally passed together with the verification request.

source
string

Free text that the client is sending, used to show if the call/SMS was intercepted or not.

Enum: "intercepted" "manual"
400

INVALID_ARGUMENT

put/verification/v1/verifications/id/{id}
Request samples
application/json
{
  • "method": "sms",
  • "sms": {
    • "code": "123"
    }
}
Response samples
application/json
{
  • "id": "1234567890",
  • "method": "string",
  • "status": "FAIL",
  • "reason": "“Fraud”",
  • "reference": "12345",
  • "source": "intercept"
}