Start enriching your app
No Credit Card Required

Phone number verification docs

Overview

The Sinch platform can be used to verify a user's phone number by placing a flash call (missed call). The call is then intercepted by the mobile application and thus verifying that the phone number corresponds to the particular device.

This document provides detailed information on how to use the Sinch platform to verify a phone number.

As a first step, the developer's backend needs to request the verification of a phone number through the respective API request. The Sinch platform will then place the flash-call to the end user's phone. The application should then intercept the incoming call, verify that the caller CLI is the same that was provided when placing the request, block the incoming call and signal that the user is now verified.

A developer can also check the progress of an ongoing request in order to understand the status of the call. This is particularly interesting if the expected call has not arrived after a few seconds, so that the mobile application takes the appropriate action.

Complete CDR files are provided every day with information on the calls initiated and messages sent.

Phone number verification API

URI:
    https://userapi.sinch.com/[version]

Current  version is "v1"

Overview

The phone number verification API is using the same Authorization mechanism that the Sinch Platform is using. For more information see Authorization.

Methods

[Error Codes]
    40001 - Illegal parameters
    40002 - Missing parameter
    40003 - Invalid request
    40108 - Invalid credentials 
    40300 - Forbidden request       
    40301 - Invalid authorization scheme for calling the method
    40400 - Not found
    50000 - Internal error

Request verification of an identity

[POST] /verifications

Request the verification of a user, with the parameters defined in the body as described below.

Authorization

This is a protected resource and the request has to be signed.

Request
[Body]
    Identity - identity
    string - method
    map - options
    string? - reference
    string? - custom

identity An endpoint identity, as defined in the Sinch Platform API.

method The verification method. It can currently have this value:

flashCall

options A set of options that should be passed to the verification API.

options:
    string - cli
    bool? - intercepted
  • cli - the number that should be presented to the callee. This is a mandatory option for flash-calls.

  • intercepted - specifies if the call is expected to be immediately denied by the verification client. By default, if not specified, intercepted is set to true. If set to false, the platform will optimise the timeout before it stops ringing.

reference An external reference identifier that can be passed for tracking purposes.

custom Custom headers that can be passed in the call. They also appear in the CDRs.

Example

[POST] /verifications

{
    "identity": {"type": "number", "endpoint":"+46700000000"},
    "method": "flashCall",
    "options": { "cli":"+4611111111", "intercepted": false }
    "reference": "a01211cf232"
    "custom": "my custom header"
}
Response
string - id

Example

{
    "id": "123000AF23242FSD"
}

Get the status of a requested flash-call

This method is used to check if a verification call is still ongoing or how it ended. It should be used when the expected call has not been received by the client within a reasonable time window.

There are 2 ways of checking the status of a verification call: i) by providing the verification id or ii) by searching with the reference.

[GET] /verifications/id/{id}

Request the status of the verification call corresponding to the specified id.

[GET] /verifications/reference/{reference}

Request the status of the verification call that was originated with the specified reference.

Authorization

These are protected resources and the request has to be signed.

Examples

URL: [GET] https://user.sinch.com/v1/verifications/id/123000AF23242FSD
URL: [GET] https://user.sinch.com/v1/verifications/reference/a01211cf232
Response
string - id
string - method
string - status
string? - reason
string? - reference
bool - intercepted

status The status of the request with the particular verification Id. It can take these values:

PENDING
SUCCESSFUL
FAILED

reason The reason of a failed request.

intercepted Indicates if the verification call was initiated as an intercepted call.

Example

[GET] /verifications/id/123000AF23242FSD

{
    "id": "123000AF23242FSD",
    "method": "flashCall",
    "status": "SUCCESSFUL",
    "reference": "a01211cf232",
    "intercepted": true
}

CDR - Phone number verification

CDR for Flash-call verification

With each call, a Call Detail Record (CDR) entry is generated in the CDR files. CDR files can be downloaded from the developer portal. Upon request, the CDR files can also be uploaded to a S3 bucket that is provided by the customer and Sinch has write access to.

For every flash-call attempt, a new record will be added in the flash-call CDR files, as well as in the App-phone CDR files.

FieldTypeDescription
idstringA unique identifier for each verification request
UserSpaceIdintInternal identifier
CallTimetimeTime when call was made
ResultstringResult may have one of the following values "PENDING" | "SUCCESSFUL" | "FAILED"
ReasonstringThe reason why a flash-call failed
CLIstringCLI that was used for the call
IdentitystringNumber that was called to be verified
ReferencestringThe external reference supplied during the request
CustomstringCustom information that was supplied during the request
ApplicationKeystringApplication key
InterceptedboolIntercepted flash-call

The files are generated once every day and will contain the previous days' CDRs. A day spans from 00:00:00 UTC to 23:59:59 UTC. CDRs are written when the call is ended, though there are some edge cases where an app-app call CDR may be delayed in being written i.e. if there is a network failure before the call is ended.