Verification callbacks

Callback events are used to authorize and manage your verification requests and return verification results.

Verification Request EventWebhook

This callback event is a POST request to the specified verification callback URL and is triggered when a new verification request is made from the SDK client or the Verification Request API. This callback event is only triggered when a verification callback URL is specified in your dashboard.

Request
Request Body schema: application/json
required
id
required
string

The ID of the verification request.

event
required
string

The type of the event.

Value Description
VerificationRequestEvent

Event received onto verification request

method
required
string

The verification method.

Enum Value Description
sms

Verification by SMS message with a PIN code.

flashcall

Verification by placing a flash call (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.

required
object (Identity)

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

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 (Price)
Responses
200

A successful response.

Response Schema: application/json
One of:
action
required
string (VerificationEventResponseAction)

Determines whether the verification can be executed.

Enum Value Description
allow

Verification allowed

deny

Verification denied

object
Request samples
application/json
{
  • "id": "1234567890",
  • "event": "VerificationRequestEvent",
  • "identity": {
    • "type": "number",
    • "endpoint": "+11235551234"
    },
  • "reference": "string",
  • "custom": "string",
  • "method": "sms",
  • "price": {
    • "currencyId": "USD",
    • "amount": 0.0127
    }
}
Response samples
application/json
{
  • "action": "allow",
  • "sms": {
    • "code": "3688",
    • "acceptLanguage": [
      ]
    }
}

Verification Result EventWebhook

This callback event is a POST request to the specified verification callback URL and triggered when a verification has been completed and the result is known. It's used to report the verification result to the developer's backend application. This callback event is only triggered when the verification callback URL is specified in your dashboard.

Request
Request Body schema: application/json
required
status
required
string (VerificationStatus)

The status of the verification

Enum Value 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.

id
required
string

The ID of the verification request.

event
required
string

The type of the event.

Value Description
VerificationResultEvent

Notification Event received onto verification result

method
required
string (VerificationMethod)

The type of the verification request.

Enum Value Description
sms

Verification by SMS message with a PIN code.

flashcall

Verification by placing a flashVerificationResultEvent call (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.

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.

required
object (Identity)

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

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.

reason
string (VerificationStatusReason)

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

Enum Value Description
Fraud

Fraudulent activity.

Not enough credit

Not enough credit in dashboard account.

Blocked

Blocked number.

Denied by callback

Callback response denied the verification.

Invalid callback

Callback was invalid.

Internal error

Internal server error.

Destination denied

Verification destinaton denied.

Network error or number unreachable

Network error or destination number is otherwise unreachable.

Failed pending

Pending failure.

SMS delivery failure

Could not deliver SMS.

Invalid CLI

CLI is invalid.

Invalid code

Input code is invalid.

Expired

Verification request has expired.

Hung up without entering valid code

Phone call ended without entering code.

source
string (Source)

With the PIN SMS verification method, a user's phone number is verified by sending an SMS containing a PIN code that must be manually returned. If you are are using an Android handset, you could instead intercept the SMS message delivery and capture the PIN code automatically.

Enum Value Description
intercepted

PIN verification was performed automatically

manual

PIN verification was manually performed

Responses
200

You must return an empty 200 response.

Response Schema: schema
Schema not provided
Request samples
application/json
{
  • "id": "1234567890",
  • "event": "VerificationResultEvent",
  • "identity": {
    • "type": "number",
    • "endpoint": "+11235551234"
    },
  • "reference": "string",
  • "custom": "string",
  • "method": "sms",
  • "status": "PENDING",
  • "reason": "Expired",
  • "source": "intercepted"
}

SMS Delivered EventWebhook

This callback event is a POST request to the specified verification callback URL and is triggered when an SMS delivery receipt is received. It is used to report the final delivery status of the verification SMS. This callback event is only triggered when a verification callback URL is specified in your dashboard.

Request
Request Body schema: application/json
required
id
required
string

The ID of the verification request.

event
required
string

The type of the event.

Value Description
VerificationSmsDeliveredEvent

Event received onto verification request

smsResult
required
string

The result of the SMS delivery. Possible values can be extended in the future.

Enum Value Description
Successful

SMS delivered to user successfully

Failed

SMS delivery to user failed

custom
string

Can be used to pass custom data in the request.

reference
string

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

Responses
200

You must return an empty 200 response.

Response Schema: schema
Schema not provided
Request samples
application/json
{
  • "id": "1234567890",
  • "event": "VerificationSmsDeliveredEvent",
  • "smsResult": "Successful",
  • "custom": "string",
  • "reference": "string"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.