## API URL URL used to send HTTP requests: ```url https://portal.bulkgate.com/api/1.0/advanced/promotional ``` > [!NOTE] > If the request does not reach its destination, repeat it on the [backup server](https://www.bulkgate.com/en/docs/api-administration-tokens/api-backup-server/) `backup1.bulkgate.com`. ## Supported HTTP methods - `POST` - `application/json` ```http POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Parameters table | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------:|:-------------:| | application_id | [Application ID](https://www.bulkgate.com/en/docs/api-administration-tokens/api-administration/) | **Yes** | - | | application_token | [Application token](https://www.bulkgate.com/en/docs/api-administration-tokens/api-tokens/) | **Yes** | - | | number | Array of recipients - [Value number](#value-number) | **Yes** or `admins` or `groups` | - | | groups | Array of numbers of groups in BulkGate address book. [More info](https://www.bulkgate.com/en/docs/advanced-api/advanced-promotional-groups/) | **Yes** or `number` or `admins` | - | | admins | Array of numbers of BulkGate administrators receiving notifications. [More info](https://www.bulkgate.com/en/docs/advanced-api/advanced-promotional-admins/) | **Yes** or `number` or `groups` | - | | text | Text of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encoding | **Yes**, if `number` is given by the array of numbers or the parameter `groups` or `admin` is used | - | | unicode | `Yes`/`true`/`1` for Unicode SMS, no/false/0 for 7bit SMS | No | `false` | | sender_id | Sender ID, see [Sender ID type](#sender-id-type-sender-id) | 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)](https://www.bulkgate.com/en/helpdesk/mobile-connect/mobile-connect-install/) | No | `null` | | country | Provide recipient numbers in international format (with prefix, for e.g `44`), or add [country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`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,](https://en.wikipedia.org/wiki/Unix_time) or [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) See examples below | No | Now | | duplicates_check | Select **`same_text`** to prevent sending duplicate messages to the same phone number. Disable the possibility to send a message with either the same or different text to the same number with **`same_number`**. If **`null`** no duplicates will be removed. Duplicates are removed **within a single batch only**, not across requests. | No | `null` | | tag | Message label for subsequent retrieval of the user. | No | - | ### Value `number` The value number can be written in two ways: - Array of phone numbers ```json [ "447820125799", "447820100234", "420606123456" ] ``` - Associative array with diagram `number`,` text`, and `variables`, where the only required parameter is` number`. If `number` is not filled in, the message skips. ```json [ {"number": "447820125799", "text": "test1 ", "variables": {"a": 5}}, {"number": "447820100234", "text": "test2 ", "variables": {"b": 5}}, {"number": "420606123456", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ] ``` You can add variables from the array `variables` into the template of parameter `text`. ### Sender ID type `sender_id` | VALUE | MEANING | |:-----------|:---------------------------------------------------------------------| | `gSystem` | System number | | `gShort` | Short Code | | `gText` | Text sender | | `gMobile` | [Mobile Connect](https://www.bulkgate.com/en/helpdesk/mobile-connect/mobile-connect-install/) | | `gPush` | Mobile Connect push - Sends a notification to the Mobile Connect app | | `gOwn` | Own number (requires number verification) | | `gProfile` | [BulkGate Profile ID](https://www.bulkgate.com/en/helpdesk/sms/sender-id-profile/) | | `` | BulkGate Profile ID | ## Request examples **Example of full request:** ```http-json POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ {"number": "447820125799", "text": "test1 ", "variables": {"a": 5}}, {"number": "447820100234", "text": "test2 ", "variables": {"b": 5}}, {"number": "420606123456", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ], "unicode": true, "groups": [1, 2], "admins": [1, 4], "text": "Hello, ", "sender_id": "gText", "sender_id_value": "BulkGate", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00" } ``` **Example of a request to enter recipients by the array of numbers and to schedule the time in the unix timestamp:** ```http-json POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ "447820125799", "447820100234", "420606123456" ], "text": "Hello, ", "schedule": "1526992636" } ``` ## Response **In case of success:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 1, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "sms_id": "idyrcmdd-0", "part_id": [ "idyrcmdd-0_1", "idyrcmdd-0" ], "number": "420775123456", "channel": "sms" }, { "status": "scheduled", "sms_id": "idyrcmdd-1", "part_id": [ "idyrcmdd-1_1", "idyrcmdd-1" ], "number": "4206061234566", "channel": "sms" }, { "status": "invalid_number", "code": 400, "error": "Invalid phone number", "detail": null, "number": "44771447678", "channel": "sms" } ] } } ``` 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.](https://www.bulkgate.com/en/helpdesk/sms/message-concatenation/) **In case of error:** ```json { "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null } ``` ```json { "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](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/) - **code** represents http error - **detail** is an additional info about the error See all the error types for Simple API and Advanced API [here.](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/)