{"openapi":"3.0.0","info":{"title":"Smart Verify API","version":"1.0","description":"The Telesign Smart Verify API decides whether it is most effective to send a one-time passcode in an SMS or in a voice message.","contact":{"name":"Telesign Customer Support Team","email":"support@telesign.com"}},"servers":[{"url":"https://rest-ww.telesign.com"}],"paths":{"/v1/verify/smart":{"post":{"summary":"Send smart verify code","operationId":"sendSmartVerifyCode","responses":{"200":{"description":"Your request was fulfilled and resulted in a new resource being created. Code against the status or error code and use that rather than the HTTP status response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"type":"object","properties":{"sub_resource":{"type":"string","description":"The channel that the service used to send this message.","example":"sms","enum":["sms","voice"]},"numbering":{"$ref":"#/components/schemas/ScoreNumbering"},"phone_type":{"$ref":"#/components/schemas/ScorePhoneType"},"carrier":{"$ref":"#/components/schemas/Carrier"}}}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[],"status":{"updated_on":"2020-08-27T17:28:49.559307Z","code":290,"description":"Message in progress"},"numbering":{"original":{"phone_number":"7833012348","complete_phone_number":"17833012348","country_code":"1"},"cleansing":{"call":{"cleansed_code":100,"country_code":"1","max_length":10,"min_length":10,"phone_number":"7833012348"},"sms":{"cleansed_code":100,"country_code":"1","max_length":10,"min_length":10,"phone_number":"7833012348"}}},"phone_type":{"code":"2","description":"MOBILE"},"carrier":{"carrier_id":"string","name":"Verizon"}}}}}}},"400":{"description":"Bad request, the request could not be understood by the server due to malformed syntax. Code against the status or error code and use that rather than the HTTP status response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/SmartVerifyShared"}]},"examples":{}}}},"401":{"description":"Unauthorized, the request requires user authentication. Code against the status or error code and use that rather than the HTTP status response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/SmartVerifyShared"}]}}}},"404":{"description":"Not Found, the server has not found anything matching the Request-URI. Code against the status or error code and use that rather than the HTTP status response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/SmartVerifyShared"}]}}}},"405":{"description":"Responses are based on the subresource used. Code against the status or error code and use that rather than the HTTP status response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/SmartVerifyShared"}]}}}},"429":{"description":"Too Many Requests, the user sent too many requests in a given amount of time. Code against the status or error code and use that rather than the HTTP status response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/SMSVerifySuccessResponse"}]}}}},"503":{"description":"Service Unavailable, system unavailable, try again. Code against the status or error code and use that rather than the HTTP status response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/SMSVerifySuccessResponse"}]}}}}},"description":"Use this action to send a one-time passcode (OTP) to your end user with the Telesign Smart Verify API. The service decides whether it is most effective to send the code in an SMS or in a voice message.\n\n## General requirements\n* **Authentication:** [Basic](doc:authentication#basic-authentication) (easiest to implement)\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Accepts:** `application/x-www-form-urlencoded`\n* **Responds with:** `application/json`","parameters":[{"schema":{"type":"string"},"in":"header","name":"Content-Type","description":"application/x-www-form-urlencoded","required":true}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"The end user's phone number you want to send a message to, including the country code, as a string of digits without spaces or special characters, beginning with the country dialing code."},"ucid":{"type":"string","description":"An abbreviation specifying a use case. Valid options are:\n* ATCK - for use in a 2FA situation like updating an account or logging in\n* BACF - for creating an account where the service may be vulnerable to bulk attacks and fraudsters\n* BACS - for creating an account where the service may be vulnerable to bulk attacks or individual spammers\n* CHBK - for use when someone is trying to buy something expensive or unusual and you want to verify it is really them\n* CLDR - calendar event\n* LEAD - for use in a situation where you require a person to enter personal information in order to obtain information about something like a loan or realty or school, and you want to check if the person is bogus or not\n* OTHR - if you have a situation not addressed by other tags\n* PWRT - for use in a situation where a passwor reset is required\n* RESV - for use when you have end users making reservations and not showing up, and you want to be able to include phone verification in the loop\n* RXPF - for use when you are trying to prevent prescription fraud\n* SHIP - for use when you are sending a shippingnotification\n* THEF - for use when you are trying to prevent an end user from deactivating or redirecting a phone number in order to take over someone else's identity\n* TRVF - for use when you are transferring moneyand you want to check to see if it is approved by sending a text message or phone call to your end user. This is similar to CHBK, but is specifically for a money transaction\n* UNKN - if you have a situation not addressed by other tags (same as OTHR).\n"},"tts_message":{"type":"string","description":"If you choose to pass a custom message, you use this parameter to indicate what the custom message would be for text to speech (TTS). You MUST set the language parameter if you use this parameter. If a language is not supported, Telesign may choose a default for you. If you do not set the language tag, United States English is assumed. Make sure to use $$CODE$$ in your message string, as this will generate and insert a random string with appropriate length as part of your TTS message."},"language":{"type":"string","description":"If you use the tts_message parameter you must set the language. Choose from the list of [supported languages](/enterprise/docs/voice-verify-supported-languages-for-text-to-speech) also used by the Telesign Voice Verify API."},"sms_message":{"type":"string","description":"If you choose to pass a custom message, you use this parameter to indicate what the custom message would be if an SMS is sent."},"preference":{"type":"string","description":"Overrides the service's automatic method selection (SMS falling back on voice call), and attempts to force it to use your specified method. You can specify either `Voice Verify` (use call) or `SMS Verify` (use SMS) as the recommended method to attempt. Telesign uses the override method whenever possible. Telesign may ignore this specified method if the destination device does not support it.","enum":["SMS Verify","Voice Verify"]},"ignore_risk":{"type":"boolean","description":"Overrides the service's automatic method selection (SMS falling back on voice call), and attempts to force it to use your specified method. You can specify either `Voice Verify` (use call) or `SMS Verify` (use SMS) as the recommended method to attempt. Telesign uses the override method whenever possible. Telesign may ignore this specified method if the destination device does not support it."}},"required":["phone_number"]}}},"description":""},"deprecated":true,"tags":["One-time passcodes"]}}},"components":{"schemas":{"Carrier":{"title":"Carrier","type":"object","description":"Contains details about the company that provides telecommunications services for this phone number.","properties":{"carrier_id":{"type":"string","description":"An ID specifying this carrier. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response."},"name":{"type":"string","description":"The name of this carrier.","example":"Verizon"}}},"SMSVerifySuccessResponse":{"title":"SMSVerifySuccessResponse","description":"","allOf":[{"type":"object","properties":{"verify":{"type":"object","description":"Contains properties related to the verification status.","properties":{"code_state":{"type":"string","description":"Indicates whether the verification code you provided in your request matches that sent by Telesign to the end-user. At this point in the verification process, the status is always `UNKNOWN`.","enum":["UNKNOWN"],"example":"UNKNOWN"},"code_entered":{"type":"string","description":"Always set to an empty string. There is no code entered by the end user at this point in the verification process."}}},"additional_info":{"type":"object","description":"Properties related to optional features you have enabled through our Customer Support Team.","properties":{"mcc":{"type":"string","description":"Mobile country code (MCC) of the destination number."},"mnc":{"type":"string","description":"Mobile network code (MNC) of the destination number."},"price":{"type":"string","description":"The price of the message you are sending."}}}}},{"$ref":"#/components/schemas/VerifyPlusResPackages"}],"x-examples":{}},"ScoreNumbering":{"title":"ScoreNumbering","type":"object","description":"Contains properties related to the numbering attributes of the specified phone number. This object is only included if enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).","properties":{"original":{"type":"object","description":"Contains details about the original phone number included in the request.","properties":{"phone_number":{"type":"string","description":"The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"7833012348"},"complete_phone_number":{"type":"string","description":"The base phone number prefixed with the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"17833012348"},"country_code":{"type":"string","description":"The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for the United Kingdom is `44`.","example":"1"}}},"cleansing":{"type":"object","description":"Contains details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.","properties":{"call":{"type":"object","description":"Contains cleansing details for the phone number if it is enabled to receive voice calls.","properties":{"cleansed_code":{"type":"integer","description":"One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.","example":100},"country_code":{"type":"string","description":"The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.","example":"1"},"max_length":{"type":"integer","description":"The maximum number of digits allowed for phone numbers with this country dialing code.","example":10},"min_length":{"type":"integer","description":"The minimum number of digits allowed for phone numbers with this country dialing code.","example":10},"phone_number":{"type":"string","description":"The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"7833012348"}}},"sms":{"type":"object","description":"Contains cleansing details for the phone number if it is enabled to receive SMS.","properties":{"cleansed_code":{"type":"integer","description":"One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.","example":100},"country_code":{"type":"string","description":"The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.","example":"1"},"max_length":{"type":"integer","description":"The maximum number of digits allowed for phone numbers with this country dialing code.","example":10},"min_length":{"type":"integer","description":"The minimum number of digits allowed for phone numbers with this country dialing code.","example":10},"phone_number":{"type":"string","description":"The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"7833012348"}}}}}}},"ScorePhoneType":{"title":"ScorePhoneType","type":"object","description":"This object is only included if enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).","properties":{"code":{"type":"string","description":"One of the [phone type codes](/enterprise/docs/codes-languages-and-time-zones#phone-type-codes).","example":"2"},"description":{"type":"string","description":"Text describing the phone type.","example":"MOBILE"}}},"ScoreRisk":{"title":"ScoreRisk","type":"object","description":"Contains properties related to the risk score for the specified phone number. Only returned when this feature has been enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).","properties":{"level":{"type":"string","example":"low","description":"The severity of the risk. [Score Scales](/enterprise/docs/intelligence-get-started#score-scales) provides a table with risk levels."},"recommendation":{"type":"string","description":"The action that Telesign recommends that you take based on the risk score.","example":"allow","enum":["allow","flag","block"]},"score":{"type":"integer","description":"The risk score for this phone number."}}},"errorObject":{"type":"object","title":"errorObject","description":"Contains properties related to an error that occurred during processing of the request.","properties":{"code":{"type":"integer","description":"A numeric code specifying which error occurred.","example":-10001},"description":{"type":"string","description":"Text describing the error that occurred.","example":"Invalid Request: PhoneNumber Parameter"}}},"SIMSwapResponse":{"type":"object","title":"SIMSwapResponse","description":"Properties related to the SIM Swap check for this transaction. This is only included if enabled by our [Customer Support Team](mailto:support@telesign.com).","properties":{"swap_date":{"type":"string","description":"The date of the SIM swap, if one is detected. ","example":"2018-09-05"},"swap_time":{"type":"string","description":"The time of the SIM swap, if one is detected. ","example":"22:00:00"},"risk_indicator":{"type":"string","description":"Indicates the likelihood that a SIM swap occured for this number. The response ranges between `1` and `4`.\n* `1` - **(very low)** Swap did not occur or it occurred 15+ days ago. \n* `2` - **(low)** Swap occurred between 3 and 14 days ago. \n* `3` - **(medium)** Swap occurred in the last 72 hours. \n* `4` - **(high)** Swap occurred in the last 24 hours.","example":"1"},"status":{"type":"object","description":"Contains properties related to the status of the SIM Swap check.","properties":{"code":{"type":"integer","description":"A code indicating the status of your request. ","example":2800},"description":{"type":"string","description":"Description of the status of your request.","example":"Request successfully completed"}}}}},"sharedResponseSchema":{"title":"sharedResponseSchema","type":"object","properties":{"reference_id":{"type":"string","description":"A unique, randomly generated hex value that identifies your web service request.","example":"0123456789ABCDEF0123456789ABCDEF","minLength":32,"maxLength":32},"sub_resource":{"type":"string","example":"sms","description":"The subresource in the URL accessed by this request."},"errors":{"type":"array","description":"Contains an object specifying each error that occurred. If no errors occurred, the array is empty.","items":{"$ref":"#/components/schemas/errorObject"}},"status":{"type":"object","description":"Contains properties describing the preliminary delivery status of the SMS you sent.","properties":{"updated_on":{"type":"string","description":"An RFC 3339 timestamp indicating when the delivery status was last updated. ","example":"2020-08-27T17:28:49.559307Z"},"code":{"type":"integer","description":"A numeric code indicating the transaction status.","example":290},"description":{"type":"string","description":"Text describing the transaction status.","example":"Message in progress"}},"required":["updated_on","code","description"]}}},"VerifyPlusResPackages":{"title":"VerifyPlusResPackages","type":"object","properties":{"phone_type":{"$ref":"#/components/schemas/ScorePhoneType"},"numbering":{"$ref":"#/components/schemas/ScoreNumbering"},"sim_swap":{"$ref":"#/components/schemas/SIMSwapResponse"},"risk":{"$ref":"#/components/schemas/ScoreRisk"}}},"SmartVerifyShared":{"title":"SmartVerifyShared","type":"object","properties":{"sub_resource":{"type":"string","description":"The service that sent this response.","enum":["smart"],"example":"smart"}}}},"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Easiest to implement. See [Basic Authentication](/api-reference/authentication#basic-authentication) for more details."},"Digest":{"name":"Authorization","type":"apiKey","in":"header","description":"See [Digest Authentication](/api-reference/authentication#digest-authentication) for more details."}},"responses":{}},"security":[{"Basic":[]}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true,"samples-enabled":true},"tags":[{"name":"One-time passcodes"}]}