Sinch Verification API

openapi: 3.2.0
info:
  title: Verification | Sinch
  license:
    name: MIT
    url: https://www.sinch.com/legal
  contact:
    name: Sinch
    url: https://www.sinch.com/contact-us/
    email: support@sinch.com
  version: 2.0.1
  description: "Sinch offers a platform for phone number verification. It consists of different software development kits (the Sinch SDKs) that you integrate with your smartphone or web application and cloud based back-end services as well as a REST API. Together, they enable SMS, Flashcall, Phone Call, and Data verification in your application.\n\nVerify users with SMS, flash calls (missed calls), a regular call, or data verification. This document serves as a user guide and documentation on how to use the Sinch Verification REST APIs.\n\nThe Sinch Verification API is used to verify mobile phone numbers. It's consumed by the Sinch Verification SDK, but it can also be used by any backend or client directly.\n\nThe Sinch service uses four different verification methods:\n\n- [SMS](https://developers.sinch.com/docs/verification/api-reference/verification/section/sms-verification): Sending an SMS message with an OTP code\n- [FlashCall](https://developers.sinch.com/docs/verification/api-reference/verification/section/flashcall-verification): Placing a flashcall (missed call) and detecting the incoming calling number (CLI)\n- [Phone Call](https://developers.sinch.com/docs/verification/api-reference/verification/section/phone-call-verification): Placing a PSTN call to the user's phone and playing a message containing the code\n- [Data](https://developers.sinch.com/docs/verification/api-reference/verification/section/data-verification): By accessing internal infrastructure of mobile carriers to verify if given verification attempt was originated from device with matching phone number\n\n{% admonition type=\"info\" name=\"Note:\" %}\nIf you want to use data verification, please contact your account manager.\n{% /admonition %}\n\n## Authentication\n\nFor general information on how to use the Sinch APIs including methods, types, errors and authorization, please visit the [Authentication](https://developers.sinch.com/docs/verification/api-reference/authentication/) page.\n\nAvailable authentication methods are:\n\n- [Application Signed Request](https://developers.sinch.com/docs/verification/api-reference/authentication/application-signed-request): Strongest method, recommended for production use\n- [Basic Authentication](https://developers.sinch.com/docs/verification/api-reference/authentication/basic-authentication): Strong and easy, recommended for prototyping\n- [Public Authentication](https://developers.sinch.com/docs/verification/api-reference/authentication/public-authentication): Weak method, suitable only for specific scenarios\n\n### Authorization\n\nYou can set the minimum required authentication level in the Dashboard. Verification API rejects requests using weaker authentication methods than configured. Some endpoints may require stronger authentication than the set minimum.\n\n# FlashCall verification\n\nWith the flashCall verification method, a user's phone number is verified by triggering a \"missed call\" towards this number. The call is automatically intercepted by the Android SDK in the mobile app and blocked automatically. iOS and JavaScript use cases require manual interaction where user has to enter incoming phone call number in the application.\n\nTo initiate a flashCall verification, visit [Android SDK documentation](https://developers.sinch.com/docs/verification/android/android-the-verification-process). For additional security, it's recommended that you control which verification requests should proceed and which ones not, by listening in your backend for the [Verification Request Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationrequestevent) and respond accordingly. Your backend will be notified on the result of the verification with the [Verification Result Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationresultevent).\n\n# SMS verification\n\nWith the SMS verification method, a user's phone number is verified by sending an SMS containing an OTP code to this number. In the case of iOS or JavaScript, the user needs to enter the OTP manually or semi-manually in the application, while for Android there is an option of intercepting the SMS message delivery and capturing the OTP code automatically.\n\nTo initiate an SMS verification, check the [iOS](https://developers.sinch.com/docs/verification/ios.md) or [Android](https://developers.sinch.com/docs/verification/android.md) documentation. For additional security, it's recommended that you control which verification requests should proceed and which ones not, by listening in your backend for the [Verification Request Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationrequestevent) and respond accordingly. Your backend will be notified on the result of the verification with the [Verification Result Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationresultevent).\n\n## Set SMS language\n\nIt's possible to specify the content language for SMS verification. The desired language is set in the initiate verification request 'Accept-Language' header. Setting this header is optional. If not included the application's default SMS content language is used, which by default is en-US. If an SMS template for the desired language is not found it's defaulted to 'en-US' unless a different default language has been defined for the requesting application.\nMore information on the 'Accept-Language' header can be found from [IETF](https://tools.ietf.org/html/rfc3282) and the [HTTP/1.1 documentation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4).\n\n{% admonition type=\"info\" name=\"Note:\" %}\nThe 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](https://community.sinch.com/t5/SMS/Sinch-US-Short-Code-Onboarding-Overview/ta-p/7085).\n{% /admonition %}\n\n_Example_ - SMS verification specifying content language\n\n```html\nHeaders: ... Accept-Language: es-ES ... [POST]\nhttps://verification.api.sinch.com/verification/v1/verifications\n```\n\n```json\n{\n  \"identity\": { \"type\": \"number\", \"endpoint\": \"+46700000001\" },\n  \"method\": \"sms\"\n}\n```\n\nThe actual language that was selected is returned in the `Content-Language` HTTP content header. As outlined above, this may differ from the requested language due to either that language not having SMS content defined, or it being overridden by provider requirements.\n\n_Example_ - SMS verification response with selected content language\n\n#### Response\n\n```html\nHeaders: ... Content-Length: 103 Content-Language: es-ES Content-Type:\napplication/json; charset=utf-8 Expires: -1 ...\n```\n\n```json\n{\n  \"id\": \"1087388\",\n  \"sms\": {\n    \"template\": \"Tu código de verificación es {{CODE}}.\",\n    \"interceptionTimeout\": 120\n  }\n}\n```\n\n# Phone Call verification\n\nWith the Phone Call verification method, a user's phone number is verified by receiving a phone call and hearing a pre-recorded or text-to-speech message containing OTP code. The user is then expected to enter this code in the application.\n\nTo initiate a Phone Call verification, check the [Start Verification](https://developers.sinch.com/docs/verification/api-reference/verification/verifications-start/startverification) documentation. For additional security, it's recommended that you control which verification requests should proceed and which ones not, by listening in your backend for the [Verification Request Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationrequestevent) and respond accordingly. Your backend will be notified on the result of the verification with the [Verification Result Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationresultevent).\n\n# Data verification\n\nWith the data verification method, a user's phone number is verified by mobile carrier's infrastructure itself. This method requires cellular data usage on end-user's device and is currently limited in its coverage.\n\n{% admonition type=\"info\" name=\"Note:\" %}\nIf you want to use data verification, please contact your account manager.\n{% /admonition %}\n\n# How to use the Verification APIs\n\nIn combination with the Mobile or Web SDK (recommended)\n\nThe following diagram shows how to use the Verification APIs when using the iOS, Android or JavaScript SDKs to initiate a verification.\n\n![verification.png](https://developers.sinch.com/images/verification/1ad7295-verification.png)\n\n{% admonition type=\"warning\" name=\"Important!\" %}\nIn this scenario, the _Verification Request_ and _Report Verification_ APIs don't need to be called explicitly by the app, since the SDK is handling that for you.\n{% /admonition %}\n\nIf you have configured a verification callback URL in the Sinch Portal (recommended), with every verification that's initiated by the app, Sinch will send a [Verification Request Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationrequestevent) to your backend, to get permission to perform the verification. If your backend allows the verification request to proceed, Sinch will trigger a flashcall, SMS or call towards the phone to be verified. Once the phone receives the flash-call, SMS or voice call, the SDK will report back the CLI or OTP respectively so that the Sinch dashboard can compare its validity. The Sinch backend responds with the result of the verification to the client and sends a [Verification Result Event](https://developers.sinch.com/docs/verification/api-reference/verification/verification-callbacks/verificationresultevent) to your backend. The status of a verification can also be queried ad-hoc by using the \"Query Verification\" APIs.\n\n## Without the mobile or web SDK\n\nIf you are not using the mobile or web Verification SDKs, then you need to implement all the client logic for intercepting calls (in case of flashcalls) and reporting the CLI or OTP (in case of SMS or Phone Call verification) inside your app. The following diagram shows how to use Sinch Verification in this scenario.\n\n![verification_without_sdk.png](https://developers.sinch.com/images/verification/82d9a08-verification_without_sdk.png)\n\nThe verification requests will be triggered from your backend towards Sinch with the [Verification Request API](https://developers.sinch.com/docs/verification/api-reference/verification/verifications-start/startverification), by doing a [signed request](https://developers.sinch.com/docs/verification/api-reference/authentication/callback-signed-request). Sinch dashboard will respond with the CLI filter (for flashcalls) or the template (in case of an SMS), or the polling intervals (in case of a Phone Call). As soon as the flashcall or SMS is received by your app, your backend will need to report back to Sinch the CLI or OTP that was reported through the [Report Verification API](https://developers.sinch.com/docs/verification/api-reference/verification/verifications-report/reportverificationbyidentity). Sinch will respond with the result of the verification.\n"
servers:
- url: https://verification.api.sinch.com
security:
- Basic: []


# --- truncated at 32 KB (87 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-verification-api-openapi.yml