Smart 2FA
Overview
Smart 2FA API lets you to send One Time Passowrd (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.
User enters your application
User visits your website or mobile app and attempts to log into his account, authorize a transaction, or perform another action that requires two-factor authentication from a new device.
User is prompted to enter his phone number
CPaaS receives the login attempt and prompts the user to enter his phone number in order to authorize the new device.
PIN code is sent to the user via SMS, phone call or email depending on API called
Once the user enters a valid phone number, from your application you will need to ask CPaaS to send a verification code to that phone number by using the HTTP REST API Call Below.
Categories
2FA can be broadly classified into four categories:
Sending One-Time Passwords - API Reference
Sending a verification code requires basic authorization that includes your account SID and auth token. Below is the format you have to use in order to send a verification code to the user’s phone number.
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: <engine>.<language-code> 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. |
workflow (Optional) |
Workflow Name to apply corresponding workflow template. For further details please look at the Workflow 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 Error’s 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 |
497 |
409 |
Invalid Limits. There is no Limits with name "XXX" |
Send API is called with Limits name that is not defined. |
Send API |
505 |
409 |
Invalid Workflow Name: "XXX" |
Send API is called with Workflow name that is not defined. |
Send API |
Example
{
"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:
curl -X POST \
https://$DOMAIN/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:
{"code":200,"message":"OK","requestID":"OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"}
Verifying One-Time Passwords - API Reference
User receives the one-time PIN code via SMS, phone call or email, gets back to your application and enters it in order to complete the verification process. Verifying the code is simple and requires basic authorization that includes your account SID and auth token.
Supported Operations
HTTP Method: POST: Verifies the code that was sent through SMS, phone call or email to the destination
Request Parameters
Parameter |
Description |
service |
The name of your service. |
requestId |
The requestID was received when initiating OTP message. |
accountSid |
If OTP message was initiated on behalf on accountSid, verify will require to have same accountSid to be able to verify the OTP request. |
code |
The verification code that was sent to the user through SMS. |
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
verify API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error’s that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
470 |
404 |
Invalid OTP Unique Id |
Verify is called for UniqueID which is not present in-system |
Verify |
471 |
409 |
OTP is already verified |
Verify is called for UniqueId which is present in-system but already verified (successfully) |
Verify |
472 |
409 |
OTP is expired |
Verify is called for UniqueId which is present in the system but expired |
Verify |
473 |
409 |
OTP is cancelled |
Verify is called for UniqueId which is present in the system but cancelled |
Verify |
474 |
401 |
Invalid OTP Code |
Verify is called for UniqueId which is present and Invalid Code is passed |
Verify |
Example
{
"service" : "2FA", // the name of your service
"requestId" : "OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY", // the unique OTP Id generated when send was called
"code": "XXXXXX" // the verification code
}
From the bash terminal you can run the command below:
curl -X POST \
https://$DOMAIN/2fa/verify \
--user ' \{your_account_SID}:\{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"service" : "2FA",
"requestId" : "OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
"code": "XXXXXX"
}
Control
Control API allows App developers to cancel already sent API or resend the OTP (resend is in roadmap)
Cancel One-Time Passwords - API Reference
Supported Operations
HTTP Method: POST: Cancel the code that was sent through SMS/ Call/ Email to the destination
Request Parameters
| Parameter | Description |
|---|---|
requestId (Required) |
The requestID was received when initiating OTP message. |
accountSid (Optional) |
If OTP message was initiated on behalf on accountSid, it requires to have same accountSid to be able to cancel the OTP request. |
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
cancel API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error’s that it can return
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
490 |
404 |
Invalid OTP Unique Id |
Control (Cancel for now, but may be other too in future) is called for UniqueID which is not present in-system |
Control |
Example:
{
"requestId":"XXXXXX" // the requestID received when initiating OTP request.
"accountSid": "XXXXX"
}
From the bash terminal you can run the command below:
curl -X POST \
https://$DOMAIN/2fa/cancel \
--user ' \{your_account_SID}:\{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"requestId" : "OTPabc2128918293123413216549879",
"accountSid": "AC123461724187287abcbas791282cf"
}
If cancel is successful, you should see below response
{"code":200,"message":"canceled","requestID":"OTPabc2128918293123413216549879"}
Session Detail Record (SDR)
Session Detail Record API allows to retrieve specific or list of OTP session and its corresponding details like which channel was used to send OTP and underlying error if channel successfully delivered OTP to end user or if there was any error. It also allows to filter based on certain criterias.
Other very important functionality exposed by SDR is Usage Report that allows to retrieve the usage of 2FA for specific period. It also allows to pass specific filter criterias.
Get list of One-Time Passwords - API Reference
Supported Operations
HTTP Method: GET or POST: Returns a list of OTP records from the provided AccountSid, subject to the provided paging, filtering and sorting URL query parameters.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of OTP records to return, starting from 0. |
pageSize |
Number of records returned per page. |
Filtering
The following filtering parameters are supported
| Query Parameter | Description |
|---|---|
accountSid |
Only include OTP list that is initiated by this specific accountSid. The accountSid should be of one of the sub account’s of this account. |
subAccounts |
If set to true, include OTP list that is initiated by all the sub accounts within this account. By default false. |
service |
Only include OTP list that match this service text, partially or fully in any position. |
channel |
Only include OTP list that is initiated via this channel. Possible values are - call |
from |
Only include OTP list that has from begins with this number/email text. For example if OTP from is “15713316943” and from filter parameter is “1”, it will match. However if from filter parameter is “3”, this record will not match. |
to |
Only include OTP list that has to begins with this number/email text. For example if OTP to is “16513333367” and to filter parameter is “1”, it will match. However if to filter parameter is “3”, this record will not match. |
targetSid |
Only include OTP list that match target sid of SMS/ Call/ Email text, partially or fully in any position. |
status |
Only include OTP list that has this status. Possible values are - success |
startTime |
Optional parameter. Only show OTP list that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show OTP list that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
channelStatus |
Only include OTP list that match underlying channel status, partially or fully in any position * For SMS, possible channel status value can be as explained in https://$DOMAIN/docs/api/sms-api.html#_status_description |
Response Parameters
search API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
The response returned is JSON body as shown in example below. Each SDR parameters are as explained below
| Response Paremeter | Description |
|---|---|
sid |
OTP UniqueId that was returned when send API was called |
service |
service parameter passed in when send API was called |
accountSid |
accountSid parameter passed in when send API was called |
dateCreated |
Date when this OTP requested was initiated |
dateUpadtes |
Date when this OTP SDR was updated |
staus |
Status of this OTP request. Possible values are successful, expired or cancelled |
uri |
Unique URI that you can call to get only this specific OTP SDR |
checks |
Number of verfiy API calls that captures additional details like if it was vaild or invalid and timestamp when verify was received by system. It also captures code used by verify API. |
events |
This captures the events like sms, call or email that was sent to end user. It has all details like sender, recipient, targetSid which is underlying platform CPaaS id. It also exposes channel Error and message if delivery of SMS, Call or email fails. |
Sorting
You can use the SortBy GET or POST query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
SortBy Attributes
| Response Paremeter | Description |
|---|---|
DateCreated |
Sort by date on which the OTP was created |
Service |
Sort by service |
Status |
Sort by status |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://$DOMAIN/2fa/search \
--user ' \{your_account_SID}:\{your_account_token}' \
-d '{ "pageSize": "2", "page":"0", "status":"success", "sortBy":"DateCreated:asc"}'
Example response:
{
"page":0,
"num_pages":3,
"page_size":2,
"total":6,
"start":0,
"end":1,
"uri":"/2fa/search",
"first_page_uri":"/2fa/search?pageSize=2&page=0&accountSid=ACae6e420f425248d6a26948c17a9e2acf&status=success",
"previous_page_uri":null,
"next_page_uri":"/2fa/search?pageSize=2&page=1&accountSid=ACae6e420f425248d6a26948c17a9e2acf&status=success",
"twoFaOtpSdrs":[
{
"sid":"OTP2a73130a3c7d492c93d0b1234596f308",
"service":"2FA",
"accountSid":"ACae6e420f425248d6a26948c17a9e2acf",
"dateCreated":"2019-08-20 10:28:08",
"dateUpdated":"2019-08-20 10:28:49",
"status":"success",
"uri":"/2fa/search/OTP2a73130a3c7d492c93d0b1234596f308",
"checks":[
{
"sid":"OTC2c58e792946b4fc389d7711cafaa5e83",
"dateReceived":"2019-08-20 10:28:49",
"status":"valid",
"code":"312209"
}
],
"events":[
{
"sid":"OTE492b1deb0a7e4a778ab95daa40e7a3f6",
"dateCreated":"2019-08-20 10:28:08",
"channel":"email",
"sender":"info@yourcompany.com",
"recipient":"jane.doe@yourcompany.com",
"targetSid":"",
"channelStatus":"queued"
}
]
},
{
"sid":"OTP02a7c56a08374eedb8789a1a038e7aae",
"service":"2FA",
"accountSid":"ACae6e420f425248d6a26948c17a9e2acf",
"dateCreated":"2019-08-20 02:43:11",
"dateUpdated":"2019-08-20 02:43:52",
"status":"success",
"uri":"/2fa/search/OTP02a7c56a08374eedb8789a1a038e7aae",
"checks":[
{
"sid":"OTC969ccb83b3cf40328c66719039c3b337",
"dateReceived":"2019-08-20 02:43:31",
"status":"invalid",
"code":"847992"
},
{
"sid":"OTC6991f661e3354a6fa1e0393c95168069",
"dateReceived":"2019-08-20 02:43:52",
"status":"valid",
"code":"347469"
}
],
"events":[
{
"sid":"OTEb6f211a28ed0412bb2c097a428d2ad5a",
"dateCreated":"2019-08-20 02:43:11",
"channel":"sms",
"sender":"12012751398",
"recipient":"919960639901",
"targetSid":"SM286fa07039ab498d80bd44d4cc91ac3c",
"channelStatus":"delivered"
}
]
}
]
}
Get single One-Time Passwords - API Reference
Supported Operations
HTTP Method: GET: Return OTP session information which is identified by OTP Sid.
Response Parameters
search API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error’s that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
480 |
404 |
Invalid OTP Unique Id |
Get single OTP is called for UniqueId which is not present in-system |
Get single OTP |
Example
From the bash terminal you can run the command below:
curl -X GET \
https://$DOMAIN/2fa/search/OTPabc2128918293123413216549879 \
--user ' \{your_account_SID}:\{your_account_token}'
Example response:
{
{
"sid":"OTPe2bd1d6583194aa1aa3892cea1e6d824",
"service" : "2FA",
"accountSid":"ACae6e420f425248d6a26948c17a9e2acf",
"dateCreated":"2019-07-22 04:40:31",
"dateUpdated":"2019-07-22 04:40:31",
"status":"expired",
"uri":"/2fa/search/OTPe2bd1d6583194aa1aa3892cea1e6d824",
"checks":[],
"events":[
{
"sid":"OTE243d763ffe7747b9a56d395a9e6a7923",
"dateCreated":"2019-07-22 04:40:31",
"channel":"sms",
"sender":"120120105123",
"recipient":"120120105124",
"targetSid":"SMd0a8b9819dfa42548bd3c306daade4f3",
"channelStatus":"undelivered",
}
]
}
}
Usage record One-Time Passwords - API Reference
The Usage record REST resource provides a simple API to retrieve usage made by your 2FA account during any time period and by any usage channel. This makes it easy to build reporting and analytics tools for your application.
| Usage records doesn’t include real time data and can be delayed by maximum of 1 hour. |
Filtering
Usage filter will return usage records for passed filter. Following filtering parameters are supported.
Query Parameter |
Description |
service |
Only include Usage records that match this service text, partially or fully in any position. For example if OTP Service is “Support” and service filter parameter is “ppo”, it will match. |
channel |
Only include Usage records that is initiated via this channel. Possible values are: call, sms, email |
to |
Only include Usage records that has to begins with this number/email text. For example if OTP to is “16513333367” and to filter parameter is “1”, it will match. However if to filter parameter is “3”, this record will not match. This allows to filter Usage records sent to specific country code. |
status |
Only include Usage records that has this status. Possible values are: success, canceled, expired |
startTime |
Only include Usage records for OTP’s that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Only include Usage records for OTP’s that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
channelStatus |
Only include Usage records that match underlying channel status, partially or fully in any position. For SMS, possible channel status value can be as explained in https://$DOMAIN/docs/api/sms-api.html#_status_description For Call, possible values are as explained in “status” property in below link https://$DOMAIN/docs/api/calls-api.html#_calls_attributes |
accountSid |
Only include Usage record that is initiated by this specific accountSid. The accountSid should be of one of the sub account’s of this account. |
subAccounts |
If set to true, include Usage records that is initiated by all the sub accounts within this account. By default false. |
Examples
From the bash terminal you can run the command below:
curl -X GET \
https://$DOMAIN/2fa/usage/records?startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z \
Example Response
{
"usageRecords":[
{
"description":"2FA Usage record",
"startTime":"2020-03-16",
"endTime":"2020-03-19",
"count":10,
"successful":5,
"unsuccessful":5,
"unit":"2FA",
"uri":"/2fa/usage/records?startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z"
}
]
}
HTTP POST example
curl -X POST \
https://$DOMAIN/2fa/usage/records \
--user ' \{your_account_SID}:\{your_account_token}'
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"startTime" : "2020-03-16T18:30:00.000Z",
"endTime": "2020-03-19"
}'
Example Response
{
"usageRecords":[
{
"description":"2FA Usage record",
"startTime":"2020-03-16",
"endTime":"2020-03-19",
"count":10,
"successful":5,
"unsuccessful":5,
"unit":"2FA",
"uri":"/2fa/usage/records?startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z"
}
]
}
Example for SMS filter parameter
HTTP POST example
curl -X POST \
https://$DOMAIN/2fa/usage/records \
--user ' \{your_account_SID}:\{your_account_token}'
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"channel" : "sms"
}'
Example Response
{
"usageRecords":[
{
"description":"2FA Usage record",
"startTime":"2020-03-16",
"endTime":"2020-03-19",
"count":3,
"successful":1,
"unsuccessful":2,
"unit":"2FA",
"uri":"/2fa/usage/records?channel=sms&startTime=2020-03-16T18:30:00.000Z&endTime=2020-03-19T13:21:37.778Z"
}
]
}
Request Sub resource
The main UsageRecords list resource supports a variety of convenience subresources. In general these take the form:
/2fa/usage/records/{Subresource}
Supported subresources are
| Subresource | Description |
|---|---|
Daily |
Return Usage record on a daily basis. If no date filter is passed, last 30 days usage is retrieved. |
Monthly |
Return Usage record on a monthly basis. If no date filter is passed, last 12 months usage is retrieved |
Yearly |
Return Usage record on yearly basis. If no date filter is passed, only this year and previous year usage is retrieved. |
Today |
Return Usage record on today. |
Yesterday |
Return Usage record on yesterday. |
ThisMonth |
Return Usage record on this month. |
LastMonth |
Return Usage record on last month. |
Filters mentioned in above section can also be passed.
Examples
HTTP GET Example
curl -X GET \
https://$DOMAIN/2fa/usage/records/daily \
--user ' \{your_account_SID}:\{your_account_token}'
Example Response
{
"usageRecords":[
{
"description":"2FA Usage record",
"startTime":"2020-03-17",
"endTime":"2020-03-17",
"count":259200,
"successful":155671,
"unsuccessful":103529,
"unit":"2FA"
},
{
"description":"2FA Usage record",
"startTime":"2020-03-19",
"endTime":"2020-03-19",
"count":140404,
"successful":84220,
"unsuccessful":56184,
"unit":"2FA"
},
{
"description":"2FA Usage record",
"startTime":"2020-03-18",
"endTime":"2020-03-18",
"count":259200,
"successful":155656,
"unsuccessful":103544,
"unit":"2FA"
}
]
}
You can also test your service using Postman or any other alike client.
Common Response Error Code
Response Parameters
Below table shows Error Codes and corresponding HTTP Response across all API calls for 2FA
Error Code |
HTTP Status |
Error Message |
Description |
Category |
401 |
401 |
Validation failed |
If validation failed for provided accountSid and token |
All |
450 |
401 |
AccountSid passed is wrong or not sub-account of account “zzzzz”. |
“zzzzz” is accountSid passed in validation request, but is wrong or not sub-account of accountSid passed in authentication header. |
All |
451 |
400 |
Mandatory parameter xxx is missing. |
xxx is actual parameter name. Comma separated parameters name if multiple. |
All |
452 |
400 |
Underlying message from CPaaS |
Error returned by underlying CPaaS platform. |
All |
Limit
Limits provide the capability to enforce limitations on the number of OTP’s sent based on various Keys defined. Keys can be defined to put limits based on many parameters. Some of the examples are below
-
Phone Number
-
End User IP Address
-
Application specific Session-Id
-
Geolocation of End User IP Address
This enables developers to safeguard against malicious attacks like bots trying to sign in to an application from one specific IP address or some user intentionally trying to generate many OTP’s.
2FA provides flexibility for Developers to define Limits based on mixed Keys. For example 1 OTP per min per number but 4 OTP per min per IP address etc.
Each Limit has, Buckets associated with (maximum of 2 Buckets allowed per Limit) to put restrictions for that Limit. For example 1 OTP per 60 Seconds and 10 OTP per 86400 Seconds (24 Hrs) for Limit based on Phone Number. Which means OTP will be limited to 1 per min and maximum 10 per day for the same Phone Number recipient.
Developers have to pass a list of Limit’s when invoking Send API to enforce limits.
| If no Limit is defined by Developer or if no Limit is passed when invoking Send API, by default 1 OTP per min per recipient phone number will be applied as default. |
Order of Limit in Send API
If Developer is calling the Send API with a combination of “limits” as explained in Request Parameters of Send, the order of limits defined matters.
For example consider below two limits defined.
-
“limit_on_Session” with only one bucket [ {"name":"bucket1", "max":"1", "interval":"60"}]
-
“limit_on_phonenumber” with two buckets [{"name":"bucket1","max":"1", "interval":"30"},{ "name":"bucket2", "max":"2", "interval":"300"}]
Example 1
Developer calls send API passing below parameter with given order.
"limits" : "{ \"limit_on_Session\":\"aabbcd\", \"limit_on_phonenumber\": \"919960639903\" }"
-
timestamp “T0”: 1st Send API called. OTP will be sent.
-
timestamp “T1=T0+31 sec”: 2nd Send API called. OTP will be blocked with error code 454 and error message “Too many Otp requests to the same Limit! key: limit_on_Session with value: aabbcd”
-
timestamp “T2=T0+61 sec”: 3rd Send API called. OTP will be sent.
-
From T2 to “T0+300 sec” OTP will be blocked
Example 2
Developer calls send API passing below parameter with given order
"limits" : "{ \"limit_on_phonenumber\": \"919960639903\",\"limit_on_Session\":\"aabbcd\" }"
-
timestamp “T0”: 1st Send API called. OTP will be sent.
-
timestamp “T1=T0+31 sec”: 2nd Send API called. OTP will be sent.
-
timestamp “T2=T0+61 sec”: 3rd Send API called. OTP will be blocked
-
From T2 to “T0+300 sec” OTP will be blocked.
Base Resource URI
https://$DOMAIN
Request Parameters
| Parameter | Description |
|---|---|
name |
Mandatory. Unique Name for this Limit. Developers will pass this as key when passing Limit to Send API. |
buckets |
JSON body of Buckets. For example "buckets":[ { "name":"bucket1", "max":"1", "interval":"10" }, { "name":"bucket2", "max":"10", "interval":"86400" } ] Note interval is in seconds. |
description |
Optional. Description for this Limit |
accountSid |
Optional. Sub-Account Sid for which Limit is to be created. If not passed Limit is created for same Account calling the API |
Response Body
The Response Body will carry Code, corresponding message and data of Limit if it was successfully created. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
| Parameter | Description |
|---|---|
code |
Sub-error code in case of error |
message |
Message describing error if error occured or success message |
data |
Limit data as explained in the table below. |
Limit Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Limit Id |
accountSid |
Unique CPaaS Account wich called API to create the Limit |
accountEmail |
Unique CPaaS Account email corresponding to accountSid |
targetAccountSid |
Unique CPaaS Account for which this particular Limit is created |
targetAccountEmail |
Unique CPaaS Account email corresponding to targetAccountSid |
dateCreated |
Timestamp when this Limit was created. |
dateUpdated |
Timestamp when this Limit was updated |
name |
Unique Name of this Limit |
buckets |
JSON formatted Buckets as explained below: - name: Any descriptive name that makes sense |
description |
Description for this Limit |
uri |
Unique URI that you can call to get only this specific Enterprise |
Create Limit API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
492 |
409 |
Limit with that Name already exists |
Limit name should be unique in given Account |
Create Limit |
Example
{
"name" : "limit_on_phoneNumber",
"description" : "Limit number of OTP sent per recipient Phone Number",
"buckets":[
{
"name":"Min bucket",
"max":"1",
"interval":"10"
},
{
"name":"Max bucket",
"max":"10",
"interval":"86400"
}
]
}
From the bash terminal you can run the command below:
curl -X POST \ https://your_custom_domain/2fa/limits \ --user ' {your_account_SID}:{your_account_token}' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \ -d ‘{ "name": "limit_on_phonenumber", "buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]", "description": "limit on Phone Number" }’
If creation of limit is successful, below is the response returned:
{
"data": {
"sid": "LMe7d332c72d2f40b9bfe8982425af14bc",
"name": "limit_on_phonenumber",
"buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"uri": "/2fa/limits/search/LMe7d332c72d2f40b9bfe8982425af14bc"
},
"code": 200,
"message": "OK"
}
If creation of Limit fails, below response is returned with corresponding HTTP Error Code
{
"code": 492,
"message": "Limit with that Name already exists",
"requestID": null
}
Update Limit
The update Limit endpoint API is called to update existing Limit for a given Account.
| Updated in Bucket value will be reflected in maximum 5 mins as System caches the Buckets to avoid frequent round-trip to database. |
Request Parameters
Parameter |
Description |
limitSid |
Mandatory. Unique SID of limit that was returned when Create Limit was invoked. |
buckets |
Optional. JSON formatted Buckets as explained below name: Any descriptive name that makes sense |
description |
Optional. Description for this Limit |
| Account can update Sub-Account Limits |
Response Body
The Response Body will carry Code, corresponding message and data of Limit if it was successfully created. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
Parameter |
Description |
code |
Sub-error code in case of error |
message |
Message describing error if error occured or success message |
data |
Limit data as explained in the table. |
Update Limit API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
493 |
409 |
Invalid Limit Id |
Limit sid passed is not present in the System |
Update, Search Single, Delete Limit |
Example:
{
"description" : "Limit number of OTP sent per recipient Phone Number. Pass with Send API",
"buckets":[
{
"name":"Min bucket",
"max":"2",
"interval":"10"
},
{
"name":"Max bucket",
"max":"20",
"interval":"86400"
}
]
}
From the bash terminal you can run the command below:
curl -X PUT \
https://your_custom_domain/2fa/limits/LM88170d5b0e1f4eb3ad724ffc8131c9c1 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d ‘{
"buckets":"[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number of receiver blabla"
}’
If update of limit is successful, below is the response returned:
{
"data": {
"sid": "LM88170d5b0e1f4eb3ad724ffc8131c9c1",
"name": "limit_on_Session",
"buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number of receiver blabla",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"uri": "/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1"
},
"code": 200,
"message": "OK"
}
If update of Limit fails, below response is returned with corresponding HTTP Error Code
{
"code": 493,
"message": "Invalid Limit Id",
"requestID": null
}
Delete Limit
The delete Limit endpoint API is called to delete existing Limit for a given Account.
Request Parameters
Parameter |
Description |
limitSid |
Mandatory. Unique SID of limit that was returned when Create Limit was invoked. |
| Account can Delete SubAccount Limits |
Response Body
The Response Body will carry Code, corresponding message and data of Limit if it was successfully deleted. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
Parameter |
Description |
code |
Sub-error code in case of error |
message |
Message describing error if error occured or success message |
data |
Limit data as explained in the table. |
Delete Limit API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
493 |
409 |
Invalid Limit Id |
Limit sid passed is not present in the System |
Update, Search Single, Delete Limit, Create Bucket |
Example:
From the bash terminal you can run the command below:
curl -X DELETE \
https://your_custom_domain.com/2fa/limits/LM4d9cfa53230848199d787a99f1b431a4 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
If delete of limit is successful, below is the response returned:
{
"data": {
"sid": "LM4d9cfa53230848199d787a99f1b431a4",
"name": "limit_on_IP",
"buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on IP",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"uri": "/2fa/limits/search/LM4d9cfa53230848199d787a99f1b431a4"
},
"code": 200,
"message": "OK"
}
If delete of Limit fails, below response is returned with corresponding HTTP Error Code
{
"code": 493,
"message": "Invalid Limit Id",
"requestID": null
}
Get list of Limits
List Limits API allows users to list all the Limits created under that “Account” or “Sub-Account”
Paging
The following paging parameters are supported
Query Parameter |
Description |
page |
Which page of Limit records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
Query Parameter |
Description |
name |
Optional parameter. Only show Limits that match name text, partially or fully. |
accountSid |
Only include Limits list that is initiated by this specific accountSid. The accountSid should be one of the sub accounts of this account. |
subAccounts |
If set to true, include Limits that are associated to all the sub accounts within this account. By default false. |
startTime |
Optional parameter. Only show limits that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Limits that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of Limits is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Parameters
Search Limit API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
Code |
Description |
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
List of Limits data of search as explained in table below |
Data parameters
Data Parameter |
Description |
result |
Limits data as explained in the table 6.1.5.1 Limit Data Parameter. |
pageSize |
Number of records returned per page. |
total |
Total Number of records |
page |
Which page of records to return. |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example:
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/2fa/limits/search?pageSize=2&page=0 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"result": [
{
"sid": "LM88170d5b0e1f4eb3ad724ffc8131c9c1",
"name": "limit_on_Session",
"buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number of receiver blabla",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"uri": "/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1"
},
{
"sid": "LMe7d332c72d2f40b9bfe8982425af14bc",
"name": "limit_on_phonenumber",
"buckets": "[{ \"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{ \"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"uri": "/2fa/limits/search/LMe7d332c72d2f40b9bfe8982425af14bc"
}
],
"pageSize": 10,
"total": 2,
"page": 0,
"numPages": 1,
"start": 0,
"end": 1,
"firstPageUri": "/2falimits/search/?pageSize=10&page=0",
"uri": "/2falimits/search/?pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Limits
Single Limits search API allows users to retrieve specific Limits created under that “Account” or “Sub-Account”
Request Parameters
Parameter |
Description |
limitSid |
Mandatory. Unique SID of limit that was returned when Create Limit was invoked. |
| Account can get single Limits of SubAccount |
Response Parameters
Search Limits API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
Error Code |
HTTP Status |
Error Message |
Description |
Category |
493 |
409 |
Invalid Limit Id |
Limit sid passed is not present in the System |
Update, Search Single, Delete Limit |
Example:
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "LM88170d5b0e1f4eb3ad724ffc8131c9c1",
"name": "limit_on_Session",
"buckets": "[{\"name\":\"bucket1\", \"max\":\"1\", \"interval\":\"30\"},{\"name\":\"bucket2\", \"max\":\"2\", \"interval\":\"300\"}]",
"description": "limit on Phone Number of receiver blabla",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"uri": "/2fa/limits/search/LM88170d5b0e1f4eb3ad724ffc8131c9c1"
},
"code": 200,
"message": "OK"
}
Workflow
Via 2FA Workflow, developers have the best chance of reaching end users by combining SMS, or Voice in any sequence it seems fit. For example
-
Workflow 1: Send OTP via SMS, wait for 60 sec and then send OTP as Text-to-speech wait for 60 sec and finally one more time via text-to-speech. If the end user verifies the OTP successfully, workflow is stopped.
-
Workflow 2: Send OTP via Text-to-speech and wait for 60 sec and then send via Text-to-speech again.
Developers can provide any wait (timeout) period between the events. Minimum value for timeout is 15 seconds.
Create Workflow
The create Workflow endpoint API is called to create a new Workflow for a given Account.
Request Parameters
Parameter |
Description |
name |
Mandatory. Unique Name for this Workflow. Developers will pass this as key when passing Workflow to Send API. |
channels |
JSON body of events. For example "channels":[ { "channel":"sms", "timeout":"60" }, { "channel":"voice", "timeout":"60" }, { "channel":"voice", "timeout":"60" } ] channel: indicates via which channel the OTP event should be sent to the end user. Only sms and voice are supported as of today. timeout: Time period in seconds from previous event by which if OTP is not verified, next event will be fired via Channel as defined in workflow. timeout can be a minimum 15 seconds. If value less than 15 is passed, Error is returned. Maximum 5 channels can be defined for any Workflow. |
description |
Optional. Description for this Workflow |
accountSid |
Optional. Sub-Account Sid for which Limit is to be created. If not passed Limit is created for same Account calling the API |
Response Body
The Response Body will carry Code, corresponding message and data of Workflow if it was successfully created. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
Parameter |
Description |
code |
Sub-error code in case of error |
message |
Message describing error if error occured or success message |
data |
Limit data as explained in the table below. |
Workflow Data Parameter
Data Parameter |
Description |
sid |
Unique Workflow Id |
accountSid |
Unique CPaaS Account wich called API to create the Workflow |
accountEmail |
Unique CPaaS Account email corresponding to accountSid |
targetAccountSid |
Unique CPaaS Account for which this particular Workflow is created |
targetAccountEmail |
Unique CPaaS Account email corresponding to targetAccountSid |
dateCreated |
Timestamp when this Workflow was created. |
dateUpdated |
Timestamp when this Workflow was updated |
name |
Unique Name of this Limit |
channels |
JSON formatted channels as explained below: channel: Channel via which OTP event is to be sent |
description |
Description for this Workflow |
uri |
Unique URI that you can call to get only this specific Workflow |
Create Worrkflow API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
502 |
409 |
Workflow with that name already exist |
Workflow name should be unique in given Account |
Create, Update Workflow |
504 |
409 |
Too many channels, Max is 5 |
Maximum 5 Channels can be defined for a given Workflow |
Create, Update Workflow |
507 |
409 |
Channel Timeout cannot be smaller than 15 |
If the timeout passed is less than 15 seconds, this error is returned. |
Create, Update Workflow |
Example
{
"name" : "Workflow SSV",
"description" : "Workflow to send SMS, SMS and then Voice",
"channels": [
{
"channel":"sms",
"interval":"0"
},
{
"channel":"sms",
"interval":"60"
},
{
"channel":"voice",
"interval":"60"
}
]
}
From the bash terminal you can run the command below:
curl -X POST \
https://your_custom_domain/2fa/workflows \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d ‘{
"name": "Workflow SSV",
"channels": "[{ \"channel\":\"sms\", \"interval\":\"0\"}, { \"channel\":\"sms\", \"interval\":\"60\"}, { \"channel\":\"voice\", \"interval\":\"60\"}]",
"description": "Workflow to send SMS, SMS and then Voice"
}’
If creation of limit is successful, below is the response returned:
{
"data": {
"sid": "WFe7d332c72d2f40b9bfe8982425af14bc",
"name": "Workflow SSV",
"channels":[
{
"channel":"sms",
"interval":"0"
},
{
"channel":"sms",
"interval":"60"
},
{
"channel":"voice",
"interval":"60"
}
]
"description": "Workflow to send SMS, SMS and then Voice",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"accountEmail": "jane.doe@yourcompany.com",
"targetAccountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"targetAccountEmail": "jane.doe@yourcompany.com",
"uri": "/2fa/workflows/search/WFe7d332c72d2f40b9bfe8982425af14bc"
},
"code": 200,
"message": "OK"
}
If creation of Workflow fails, below response is returned with corresponding HTTP Error Code
{
"code": 495,
"message": "Workflow with that name already exists",
"requestID": null
}
Update Workflow
The update Workflow endpoint API is called to update existing Workflow for a given Account.
Request Parameters
Parameter |
Description |
workflowSid |
Mandatory. Unique SID of Workflow that was returned when Create Workflow was invoked. |
channels |
Optional. JSON formatted Channels as explained below channel: Channel via which OTP event is to be sent |
description |
Optional. Description for this Limit |
| Account can update Sub-Account Workflows |
Response Body
The Response Body will carry Code, corresponding message and data of Workflow if it was successfully updated. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
Parameter |
Description |
code |
Sub-error code in case of error |
message |
Message describing error if error occured or success message |
data |
Workflow data as explained in the table. |
Update Workflow API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
503 |
409 |
Invalid Workflow Id |
Workflow sid passed is not present in the System |
Update, Search Single, Delete Workflow |
502 |
409 |
Workflow with that name already exist |
Workflow name should be unique in given Account |
Create, Update Workflow |
504 |
409 |
Too many channels, Max is 5 |
Maximum 5 Channels can be defined for a given Workflow |
Create, Update Workflow |
507 |
409 |
Channel Timeout cannot be smaller than 15 |
If the timeout passed is less than 15 seconds, this error is returned. |
Create, Update Workflow |
Example
{
"channels": "[{ \"channel\":\"sms\", \"interval\":\"0\"}, { \"channel\":\"sms\", \"interval\":\"60\"}, { \"channel\":\"voice\", \"interval\":\"120\"}]",
"description": "Workflow to send SMS, SMS and then Voice after double the time period"
}
From the bash terminal you can run the command below:
curl -X PUT \
https://your_custom_domain.com/2fa/workflows/WFe7d332c72d2f40b9bfe8982425af14bc \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d ‘{
"channels": "[{ \"channel\":\"sms\", \"interval\":\"0\"}, { \"channel\":\"sms\", \"interval\":\"60\"}, { \"channel\":\"voice\", \"interval\":\"120\"}]",
"description": "Workflow to send SMS, SMS and then Voice after double the time period"
}’
If update of Workflow is successful, below is the response returned:
{
"data": {
"sid": "WFe7d332c72d2f40b9bfe8982425af14bc",
"name": "Workflow SSV",
"channels":[
{
"channel":"sms",
"interval":"0"
},
{
"channel":"sms",
"interval":"60"
},
{
"channel":"voice",
"interval":"120"
}
]
"description": "Workflow to send SMS, SMS and then Voice after double the time period",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"accountEmail": "jane.doe@yourcompany.com",
"targetAccountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"targetAccountEmail": "jane.doe@yourcompany.com",
"uri": "/2fa/workflows/search/WFe7d332c72d2f40b9bfe8982425af14bc"
},
"code": 200,
"message": "OK"
}
If update of Limit fails, below response is returned with corresponding HTTP Error Code
{
"code": 499,
"message": "Invalid Workflow Id",
"requestID": null
}
Delete Workflow
The delete Workflow endpoint API is called to delete existing Workflow for a given Account.
Request Parameters
Parameter |
Description |
workflowSid |
Mandatory. Unique SID of Workflow that was returned when Create Workflow was invoked. |
| Account can Delete SubAccount Workflows |
Response Body
The Response Body will carry Code, corresponding message and data of Workflow if it was successfully deleted. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
Parameter |
Description |
code |
Sub-error code in case of error |
message |
Message describing error if error occured or success message |
data |
Workflow data as explained in the table. |
Delete Worrkflow API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the Error that it can return
Error Code |
HTTP Status |
Error Message |
Description |
Category |
503 |
409 |
Invalid Workflow Id |
Workflow sid passed is not present in the System |
Update, Search Single, Delete Workflow |
Example:
From the bash terminal you can run the command below:
curl -X DELETE \
https://your_custom_domain.com/2fa/workflows/WFe7d332c72d2f40b9bfe8982425af14bc \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
If delete of Workflow is successful, below is the response returned:
{
"data": {
"sid": "WFe7d332c72d2f40b9bfe8982425af14bc",
"name": "Workflow SSV",
"channels":[
{
"channel":"sms",
"interval":"0"
},
{
"channel":"sms",
"interval":"60"
},
{
"channel":"voice",
"interval":"120"
}
]
"description": "Workflow to send SMS, SMS and then Voice after double the time period",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"accountEmail": "jane.doe@yourcompany.com",
"targetAccountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"targetAccountEmail": "jane.doe@yourcompany.com",
"uri": "/2fa/workflows/search/WFe7d332c72d2f40b9bfe8982425af14bc"
},
"code": 200,
"message": "OK"
}
If delete of Limit fails, below response is returned with corresponding HTTP Error Code
{
"code": 499,
"message": "Invalid Workflow Id",
"requestID": null
}
Get list of Workflows
List Workflows API allows users to list all the Workflow created under that “Account” or “Sub-Account”
Paging
The following paging parameters are supported
Query Parameter |
Description |
page |
Which page of Workflow records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
Query Parameter |
Description |
name |
Optional parameter. Only show Workflows that match name text, partially or fully. |
accountSid |
Only include Workflow list that is initiated by this specific accountSid. The accountSid should be one of the sub accounts of this account. |
subAccounts |
If set to true, include Workflows that are associated to all the sub accounts within this account. By default false. |
startTime |
Optional parameter. Only show Workflows that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Workflows that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of Limits is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Parameters
Search Limit API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
The response returned is JSON body as shown in the example below. Each parameters are as explained below
Code |
Description |
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
List of Workflows data of search as explained in table below |
Data parameters
Data Parameter |
Description |
result |
Workflows data as explained in the table Workflow Data Parameter. |
pageSize |
Number of records returned per page. |
total |
Total Number of records |
page |
Which page of records to return. |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example:
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/2fa/workflows/search?pageSize=2&page=0 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"result": [
{
"sid": "WFe7d332c72d2f40b9bfe8982425af14bc",
"name": "Workflow SSV",
"channels":[
{
"channel":"sms",
"interval":"0"
},
{
"channel":"sms",
"interval":"60"
},
{
"channel":"voice",
"interval":"120"
}
]
"description": "Workflow to send SMS, SMS and then Voice after double the time period",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"accountEmail": "jane.doe@yourcompany.com",
"targetAccountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"targetAccountEmail": "jane.doe@yourcompany.com",
"uri": "/2fa/workflows/search/WFe7d332c72d2f40b9bfe8982425af14bc"
},
{
"sid": "WFe7d332c72d2f40b9bfe8982425af14bd",
"name": "Workflow SVV",
"channels":[
{
"channel":"sms",
"interval":"0"
},
{
"channel":"voice",
"interval":"60"
},
{
"channel":"voice",
"interval":"60"
}
]
"description": "Workflow to send SMS, Voice and then Voice",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"accountEmail": "jane.doe@yourcompany.com",
"targetAccountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"targetAccountEmail": "jane.doe@yourcompany.com",
"uri": "/2fa/workflows/search/WFe7d332c72d2f40b9bfe8982425af14bd"
}
],
"pageSize": 10,
"total": 2,
"page": 0,
"numPages": 1,
"start": 0,
"end": 1,
"firstPageUri": "/workflows/search/?pageSize=10&page=0",
"uri": "/workflows/search/?pageSize=10&page=0"
},
"code": 200,
"message": "OK"
}
Get Single Workflow
Single Workflow search API allows users to retrieve specific Workflow created under that “Account” or “Sub-Account”
Request Parameters
Parameter |
Description |
workflowSid |
Mandatory. Unique SID of Workflow that was returned when Create Workflow was invoked. |
| Account can get single Workflow of SubAccount |
Response Parameters
Search Limits API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
Error Code |
HTTP Status |
Error Message |
Description |
Category |
503 |
409 |
Invalid Workflow Id |
Workflow sid passed is not present in the System |
Update, Search Single, Delete Workflow |
Example:
From the bash terminal you can run the command below:
curl -X GET \
https://your_custom_domain.com/2fa/workflows/search/WF88170d5b0e1f4eb3ad724ffc8131c9c1 \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "WFe7d332c72d2f40b9bfe8982425af14bc",
"name": "Workflow SSV",
"channels":[
{
"channel":"sms",
"interval":"0"
},
{
"channel":"sms",
"interval":"60"
},
{
"channel":"voice",
"interval":"60"
}
]
"description": "Workflow to send SMS, SMS and then Voice",
"accountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"accountEmail": "jane.doe@yourcompany.com",
"targetAccountSid": "AC23f1b11bbb99a46436c365cb7bec246e",
"targetAccountEmail": "jane.doe@yourcompany.com",
"uri": "/2fa/workflows/search/WFe7d332c72d2f40b9bfe8982425af14bc"
},
"code": 200,
"message": "OK"
}