Specification v1

API URL

URL used to send HTTP requests:

https://portal.bulkgate.com/api/1.0/advanced/transactional

POST /api/1.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

It is strictly prohibited to exploit SMS notification for promotional/marketing uses. It must be used for notification purposes only - as a transactional SMS.

Parameters table

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
application_id	Application ID	Yes	-
application_token	Application token	Yes	-
number	Recipient number	Yes or admin	-
admin	Number of BulkGate administrator receiving notification. More info	Yes or number	-
text	Text of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encoding. It is possible to add variables to the template from the variables array (another parameter) Hello <first_name> <last_name> ....	Yes	-
variables	Associative array to add variables to text, for e.g.: {"first_name": "John", "last_name": "Doe"}	No	[]
unicode	Yes/true/1 for Unicode SMS, no/false/0 for 7bit SMS	No	false
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
country	Provide recipient numbers in international format (with prefix, for e.g 44), or add country code (7820125799 + GB = 447820125799). See the example of a country requirement. If the value is null, your set time zone will be used to fill in the information	No	null
schedule	Schedule the sending time and date in unix timestamp, or ISO 8601.	No	Now
duplicates_check	Select on to prevent sending duplicate messages to the same phone number. Messages with the same text sent to the same number will be removed if there is a time interval shorter than 5 mins. If off no duplicates will be removed.	No	off
tag	Message label for subsequent retrieval of the user.	No	-

Sender ID type sender_id

VALUE	MEANING
gSystem	System number
gShort	Short Code
gText	Text sender
gMobile	Mobile Connect
gPush	Mobile Connect push - Sends a notification to the Mobile Connect app
gOwn	Own number (requires number verification)
gProfile	BulkGate Profile ID
<int>	BulkGate Profile ID

Example of full request:

POST /api/1.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",   
    "number": "447820125799",
    "unicode": true,
    "text": "Hello, <first_name> <last_name>",
    "variables": {"first_name": "John", "last_name": "Doe"},
    "sender_id": "gText",
    "sender_id_value": "BulkGate",
    "country": "cz",
    "schedule": "2018-05-14T18:30:00-01:00"
}

Response to this command may be:

In case of success:

{
    "data": {
        "status": "accepted",
        "sms_id": "tmpde1bcd4b1d1",
        "part_id": [
            "tmpde1bcd4b1d1_1",
            "tmpde1bcd4b1d1"
        ],
        "number": "447820125799"
    }
}

Where:

• part_ID is the ID array of the parts of the original long message that were split because they did not meet the 160 character limit for a single message. More info here.

In case of error:

{
    "type": "invalid_phone_number",
    "code": 400,
    "error": "Invalid phone number",
    "detail": null
}

{
    "type": "unknown_identity",
    "code": 401,
    "error": "Unknown identity / unauthorized / empty application_id",
    "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

See all the error types for Simple API and Advanced API here.