Send One Time Password (OTP)

API URL

URL used to send HTTP requests:

https://portal.bulkgate.com/api/1.0/otp/send

Note

If the request does not reach its destination, repeat it on the backup server backup1.bulkgate.com.

Supported HTTP methods

POST - application/json

POST /api/1.0/otp/send HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Important

On top of request_quota_number the endpoint enforces an account-wide limit of 60 requests per minute. Exceeding it returns the_quota_of_send_per_minute_has_been_exceeded.

Parameters table

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
application_id	Application ID	Yes	-
application_token	Application token	Yes	-
number	Phone number to which send the verification code	Yes	-
country	Country code of phone number	no	The value is taken from the profile.
language	Language of the message text, one of the 100 supported ISO codes. An unknown code rejects the request. Without it the language is detected from the phone number.	no	`null`
code_type	Type of code. (`string`, `int`, or `combined`)	no	`int`
code_length	Length of verification code (4-100).	no	6
request_quota_number	The number of requests per minute for `request_quota_identification`	no	1
request_quota_identification	Identification of the "OTP user / requester" to whom the `request_quota_number` quota per minute will apply. We recommend using an IP address for this identification.	Yes	-
trials_available_resend	Limit of available resends	no	`null` - unlimited
trials_available_verification	Limit of available verification	no	`null` - unlimited
daily_limit	Limit of available requests per day (sliding for last 24 hours)	no	`null` - unlimited
daily_limit_country	Daily limit per country as a map `{"cz": 100, "sk": 50}`. When filled in, only the listed countries are allowed — any other one fails with `country_is_disabled`.	no	`null` - unlimited
expiration	Expiration of OTP request in seconds, after completion of this time request is not possible. A value below `60` is ignored and the default is used.	no	`604800` - 7 days
channel	Alternative channels. Channels are listed in a cascade, if we are unable to deliver your message via highest priority channel, channels lower in the cascade list will be used. If none of them manages to deliver sms will be used instead.	no	SMS, Viber, RCS, WhatsApp or Text2Voice

Channels

The channel object decides which channels deliver the code and in what order. The order of the keys in the request is the order of the cascade — if the first channel cannot deliver the code, the next one is tried. If none of them can, SMS is used.

SMS object

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
sender_id	Sender ID, see sender ID type	no	`gSystem`
sender_id_value	Sender value - `gOwn` (e.g. "420 777 777 777"), `gText` (e.g. "BulkGate"), `gProfile` (e.g. "423"), `gMobile` or `gPush` (KEY)	no	`null`
domain	Url of a website that uses WebOTP for auto input of received code.	no	`null`

Viber object

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
sender	Name of your registered sender for Viber	Yes	-
expiration	Seconds to wait until trying another channel	no	60
code_type	Code type required by Viber, stated on the approved OTP template.	no	`null`
code_reason	Reason for sending the code, required by Viber.	no	`null`
business_name	Business name shown in the message.	no	`null`

RCS object

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
sender	Text sender for RCS. It must be registered first — contact our support to register it.	Yes	-
expiration	Seconds to wait until trying another channel	no	60
use_card	Sends the code as a card instead of plain text.	no	`false`

WhatsApp object

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
sender	Your registered WhatsApp sender	Yes	-
template	Name of the approved WhatsApp template used to deliver the code.	No	`verification_code`
language	Template language. Without it the request-level `language` is used.	No	`null`
expiration	Seconds to wait until trying another channel in the cascade. Minimum `60`.	No	`180`

Text2Voice object

The code is read out loud. The message can be repeated so the recipient can write it down.

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
sender	Your registered caller number.	Yes	-
language	Voice language, one of the 47 supported ISO codes. Without it the request-level `language` is used.	No	`null`
prefer_gender	Preferred voice - `male` or `female`.	No	`male`
safety_statement	Prepends a safety notice to the call.	No	`true`
repeat	How many times the code is repeated during the call.	No	`1`
expiration	Seconds to wait until trying another channel in the cascade. Minimum `60`.	No	`180`

Example request

{ "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": "44777777777", "country": "gb", "language": "en", "code_type": "string", "code_length": 7, "request_quota_number": 1, "request_quota_identification": "127.0.0.1", "trials_available_resend": 2, "trials_available_verification": 5, "daily_limit": 100, "daily_limit_country": {"cz": 150, "sk": 50}, "expiration": 3600, "channel": { "rcs": { "sender": "Lt. Hagan", "expiration": 100 }, "viber": { "sender": "Lt. Hagan", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true } } }

Response

In case of success:

{ "data": { "id": "otp-65cca8b4b6a6a2.24308291", "message": { "status": "accepted", "message_id": "cascade-xjyjzh7thor3", "part_id": [ "cascade-xjyjzh7thor3" ], "number": "420777777777", "channel": "whatsapp" } } }

In case of error:

{ "type": "unknown_identity", "code": 400, "error": "Unknown identity", "detail": null }

{ "type": "invalid_input_parameters", "code": 400, "error": "Invalid input parameters", "detail": null }

Where:

type and error (description of the error) can be found in the error types table
code represents http error
detail is an additional info about the error

OTP API error types

On top of the common types the OTP API returns its own:

TYPE	WHEN IT HAPPENS
`the_quota_of_send_per_minute_has_been_exceeded`	The per-minute send quota is used up.
`the_quota_of_one_additional_resend_per_minute_has_been_exceeded`	A resend sooner than 60 s after the previous one.
`the_quota_of_one_additional_resend_has_been_exceeded`	`trials_available_resend` is used up.
`the_quota_of_one_additional_verification_has_been_exceeded`	`trials_available_verification` is used up.
`daily_limit_reached`	`daily_limit` is used up.
`country_is_disabled`	The number's country is not listed in `daily_limit_country`.
`country_daily_limit_exceeded`	The daily limit for that country is used up.
`invalid_phone_number`	The number could not be recognised.
`invalid_code`	The verified code does not match.
`unknown_channel`	The cascade contains a channel the OTP API does not know.
`request_can_not_be_created`	The request could not be created.

Was this page helpful?

Ask AI Copied