Documentation and APIs

Learn how to use our serverless platform to create voice, video and messaging applications and services by reading our getting started guide. It's the best way to become familiar with the platform architecture and capabilities.

Number Management
SMS
Anonymize
Authenticate
Engage

Authenticate

Smart 2FA API lets you to send One Time Password (OTP) using SMS, Voice or email. 2FA allows you to add a second layer of security to your Application in addition to the user-id and password. The flexibility of using any channel makes sure your users get OTP even when they experience issue with one of the channels.

Send

Base Resource URI

Environment URL
Production https://comms.tatacommunications.com
Verification Code Resource URI /2fa/send
Supported Operations

HTTP POST: Send a verification code through SMS, phone call or email to the specified destination.

Request Parameters
Parameter Description
service (Required) The name of your service.
from (Required) The source address that is making a call, or sending the SMS or email containing the verification code.
to (Required) The destination address to send the OTP message containing the verification code.
body (Required) The content of the OTP message. Use {code} as a placeholder for the location of the verification code in your SMS content. This {code} will be replaced automatically with a random code generated by the system
channel (Optional) A method for sending OTP message. There are 3 options: sms, call, email. If not passed, default is sms.
accountSid (Optional) OTP message will be sent on behalf of given accountSid. The accountSid has to be valid sub-account.
subject (Required in email channel) Email subject for the OTP message, it’s required only in email channel.
language (Optional) Text-to-Speech (TTS) language for announcing OTP message over call channel. AWS Polly is default TTS engine. To use another engine, use format like: . for example: awspolly.ja-JP. More information about language, please visit the Say-RCML documentation.
repeat (Optional) Number of times the TTS OTP message will be played. It’s only required in call channel, default value is 1.
length (Optional) Number of digits for OTP. By default, 6 digits number will be generated for OTP code.
voice (Optional) Man or woman voice for TTS call channel.
timeout (Optional) Time in seconds for which OTP is valid. Post timeout period, OTP is automatically canceled if still not successfully verified. Default is 300 seconds.
guardTime (Optional) If send is called again to send new OTP passing same service and to parameter while previous OTP generated is still valid, the previous OTP is Canceled and new OTP is sent. However if guardTime (in seconds) parameter is passed in send request, old OTP is valid for guardTime and then cancelled. This is to accomodate scenarios where the underlying SMS, Call or email channel may be slow to deliver the message and by the time new OTP is generated, user might have received old OTP.
limits (Optional) Key-Value pair Limits to restrict on number of OTPs generated based on criteria that developers select. For further details please look at Limit section.
Response
Responde Body Description
Code Sub error code for the request.
Message Message for describing sub error code.
requestID The unique OTP request identifier for the OTP request.
Response Parameters

Send API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code In addition below are the Errors that it can return

Error Code HTTP Status Error Message Description Category
453 404 Too many OTP request to same destination Number OTP is sent to same destination number within 1 min of previously sent. 2FA system limits number of OTP sent to same number to maximum one per min. Send
495 409 Invalid Limit Name: XXX Send API is called with Limits name that is not defined. Send API
Example
  copy
  
  {
  "service" : "2FA", // the name of your service
  "from" : "+XXXXXXXXX", // the SMS sender phone number
  "to" : "+XXXXXXXXXX", // the SMS recepient phone number
  "body": "Your verification code is: \{code}" // SMS body, containing the verification code
  }
  

From the bash terminal you can run the command below:

  copy
  
  curl -X POST \
  https://comms.tatacommunications.com/2fa/send \
  --user  ' \{your_account_SID}:\{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "service" : "2FA",
  "from" : "XXXXXXXXXXX",
  "to" : "ZZZZZZZZZZZ",
  "body": "Your verification code is: \{code}"
  }'
  

If send is successful, below is the response returned:

  copy
  
  {"code":200,"message":"OK","requestID":"OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"}
  Example of sending OTP with limits:
  curl -X POST \
  https://yourdomain.com/2fa/send \
  --user ' \{your_account_SID}:\{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "service" : "2FA",
  "from" : "XXXXXXXXXXX",
  "to" : "ZZZZZZZZZZZ",
  "body": "Your verification code is: \{code}",
  "limits" : { "limit_on_phone": "+1205XXXXXXX" }
  }'
  

What’s New