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

id required	string The ID of the verification request.
event required	string The type of the event.
method required	string The verification method. Enum: "sms" "flashCall" "callout"
required	object (Identity) Specifies the type of endpoint that will be verified and the particular endpoint. `number` is currently the only supported endpoint type.
	object The amount of money and currency of the verification request.
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.
acceptLanguage	Array of strings Allows you to set or override if provided in the API request, the SMS verification content language. Only used with the SMS verification method. The content language specified in the API request or in the callback can be overridden by carrier provider specific templates, due to compliance and legal requirements, such as US shortcode requirements (pdf).

Responses

200

A successful response.

Response Schema: application/json

One of:

action	string Determines whether the verification can be executed. Enum: "allow" "deny"
	object

Request samples

application/json

{"id": "1234567890",
"event": "VerificationRequestEvent",
"method": "sms",
"identity": {"type": "number",
"endpoint": "+11235551234"
},
"price": {"amount": 10.5,
"currencyId": "USD"
},
"reference": "string",
"custom": "string",
"acceptLanguage": ["es-ES"
]
}

Response samples

200

application/json

{ }

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

id

required

string

The ID of the verification request.

event

required

string

The type of the event.

method

required

string

The verification method.

Enum: "sms" "flashCall" "callout" "seamless"

required

object (Identity)

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

status

required

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"

custom

string

A custom string that can be provided during a verification request.

Responses

200

A successful response.

Response Schema: application/json

One of:

action	string Determines whether the verification can be executed. Enum: "allow" "deny"
	object

Request samples

application/json

{"id": "1234567890",
"event": "VerificationResultEvent",
"method": "sms",
"identity": {"type": "number",
"endpoint": "+11235551234"
},
"status": "PENDING",
"reason": "“Fraud”",
"reference": "12345",
"source": "intercept",
"custom": "string"
}

Response samples

200

application/json

{ }