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.

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
application/json
{
  • "action": "allow",
  • "sms": {
    • "code": 3688,
    • "acceptLanguage": "en-US"
    }
}

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
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

You must return an empty 200 response.

Response Schema: schema
Schema not provided
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"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.