# Welcome to BulkSMS Welcome to Mobivate's Bulk API platform documentation. Here you can find guides and tutorials to help you set up and use our bulk SMS messaging platform effectively. ### What is BulkSMS? Connect your apps, systems and software to our easy to use BulkSMS gateway to send bulk SMS messages to users all across the globe. ## Getting started with our API Developers 🧡️‍ our *out of the box* API solution. Get started with some useful guides:
✉️ Send SMS messagesThe perfect API to send/receive SMS messages easily.Get started
📦 Get Delivery ReceiptsHave full flexibility to receive DR's to your webhooks.Get started
🔎 Search for MessagesGet full access your message history using our API. Get started
# Introduction Explore our complete API Reference Documentation to seamlessly integrate SMS messaging into your website or application using Mobivate’s Bulk SMS APIs. Mobivate’s Bulk SMS APIs are built around standard HTTP verbs and a RESTful endpoint structure. API keys are used for authorization. All request and response payloads are formatted in JSON, making integration straightforward and predictable. ### Sending Messages SMS message delivery is handled asynchronously. When you submit a message to our platform, we immediately acknowledge receipt of the request while delivery to the handset continues in the background. If you have enabled Delivery Receipt notifications, these will be sent to your configured webhook endpoint as they are received by our system. We recommend storing and processing these receipts asynchronously on your side to ensure reliable delivery tracking.
### Authentication Authentication to the Mobivate API is performed using **Bearer tokens**. Once you have created an API key, it must be included in the `Authorization` header with every API request. #### Example ```bash -H "Authorization: Bearer YOUR_API_KEY" ``` You can create new API keys by following our guide on [Creating a new API key](/overview/introduction/creating-a-new-api-key). {% hint style="warning" %} Your API keys can grant access to your Mobivate account and should be treated as sensitive credentials. Keep your API keys secure at all times and never share them or expose them in publicly accessible locations, such as client-side code repositories, public websites, or shared documentation. {% endhint %} ### **API Base URL** All examples in this documentation use a placeholder base URL: `` The production API domain is provided by our team upon request. # Creating a new API key API keys are used to authorise your account to make requests to the Mobivate API. Each API key is associated with specific permissions and optional restrictions to help you control how it is used. To create a new API key, follow these steps: 1. Log into your [Mobivate](https://www.hub.mobivate.com) account. 2. Click the **cog icon** in the top-right corner of the page. 3. Click on **User Profile.** 4. Navigate to the **API Keys** tab. 5. Click **New API Key**. #### Permissions Each API key can be configured with specific permissions that determine which actions it can perform within the Mobivate platform. Permission requirements will vary depending on your use case, so we recommend enabling only what you need. #### Allowed IPs (IP Ranges) You can restrict an API key so it is only usable from specific IP addresses or IP ranges.\ If you do not wish to apply any IP restrictions, we recommend selecting **Anywhere (IPv4)**. #### Daily Message Limit You may optionally set a daily message limit to cap the number of messages that can be sent using an API key. A value of **0** means no limit (recommended by default). {% hint style="info" %} Daily limits reset automatically at **midnight UTC**. {% endhint %} #### Receipt URL If you want to receive delivery notifications for SMS messages outside of the Mobivate platform, you can provide a receipt (callback) URL here.\ \ If left empty, no external delivery notifications will be sent. #### Storing your API key When a new API key is created, you will have the option to **copy** it to your clipboard or **download** it. {% hint style="warning" %} For security reasons, your API key is only shown once at creation time. If you lose or forget your key, it cannot be retrieved and a new API key will need to be generated. {% endhint %} # Test API Key You can verify that your API key is valid and correctly configured by making a request to the authentication test endpoint. This endpoint does not send any messages and can be safely used during development or troubleshooting. ### `POST/GET` `/auth/test` #### Example Request Use the following `curl` command to test your API key: ```bash curl --location 'https:///auth/test' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with the API key you wish to test. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Response If the API key is valid, the API will respond with an HTTP `200 OK` status code. ```http HTTP/1.1 200 OK ``` A successful response confirms that: * The API key is valid * Authorization is working correctly * The key has access to the Mobivate API If the API key is invalid, expired, or lacks the required permissions, an appropriate `4xx` error response will be returned with a JSON-formatted error message. # Understanding Response Codes Mobivate uses standard HTTP status codes to indicate the outcome of an API request. * **2xx** status codes indicate that the request was successfully processed. * **4xx** status codes indicate an error caused by the request itself, such as authentication issues, insufficient balance, or missing or invalid parameters. When an error occurs, the response body will include a **JSON-formatted** payload describing the issue in detail, allowing you to identify and resolve the problem quickly. ### Response Codes | Attribute | Description | | --------- | ----------------------------------------------------------- | | 200 | Message submitted successfully. | | 400 | Bad request - Some of the provided parameters were invalid. | | 401 | Unauthorized - API key is invalid or has expired. | | 402 | Out of Credit - Insufficient funds to send code. | | 403 | Opted Out - Message blocked because recipient is opted out. | | 429 | Slow down - Rate limit exceeded. | | 500 | Internal error - We are experiencing a technical issue. | # Delivery Notifications (DLRs / Webhooks) ## Delivery Notifications Mobivate provides delivery notifications for SMS messages as their delivery status changes. These notifications allow you to track message progress and final delivery outcomes. ### How Delivery Notifications Work * Delivery notifications are sent on **every status change**, except when a message is initially created. * Notifications are delivered asynchronously to your configured **Delivery Endpoint (webhook)**. * Each notification contains the latest known status for the message. ### Configuring the Delivery Endpoint You can define a delivery notification endpoint in two ways: #### 1. API Key Default (Recommended) Set a default Delivery Endpoint URL for an API key in the Mobivate user interface.\ This endpoint will be used for all messages sent using that key. {% hint style="info" %} To configure a webhook via API key, please see [**Creating a new API Key**](/overview/introduction/creating-a-new-api-key). {% endhint %} #### 2. Per-Request Override You can override the default endpoint by supplying a `callbackURL` parameter when sending: * Single messages * Batch campaigns * Template-based campaigns * Alias-based messages This allows fine grained control over where delivery notifications are sent. ### Best Practices * Always return a **`200 OK`** response from your endpoint to acknowledge receipt. * Process notifications asynchronously on your side. * Store delivery receipts for auditing and reporting purposes. * Ensure your endpoint is publicly accessible and secured. {% hint style="warning" %} Delivery notifications are sent independently of message submission. {% endhint %} # Incoming Messages (MO) Inbound SMS messages sent to your virtual numbers are processed through Mobivate’s Flow Application. ### How Incoming Messages Are Handled All inbound messages are routed into the Flow system, where you can define how they should be treated using the Mobivate user interface. Available actions include: * Forwarding messages to an email address * Sending an automatic reply * Adding the sender to Opt-Out records * Custom routing or workflows (depending on configuration) {% hint style="info" %} Certain actions may affect future **outbound messaging** (e.g. opt-outs). {% endhint %} ### Configuration Inbound message behaviour is managed from the **Resources** page in the Mobivate dashboard. {% hint style="success" %} No API integration is required to receive inbound messages unless explicitly configured. {% endhint %} # Send Single SMS Message Send an SMS message to a single recipient using the Single SMS endpoint. ### `POST` `/send/single` #### Required Permission ``` create:SingleSMS ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///send/single' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "text": "test", "originator": "test", "recipient": "4479000000001", "reference": "ref", "shortenUrls": false, "excludeOptouts": true }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Request Parameters | Field | Type | Required | Description | | ---------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | Yes | The SMS message content. | | originator | string | Yes | The sender ID displayed on the recipient’s handset. | | recipient | string | Yes | The destination phone number in international format. | | reference | string | No | Your reference, will be provided as part of the delivery receipt for correlation. | | shortenUrls | boolean | No | Whether URLs in the message should be automatically shortened. | | excludeOptouts | boolean | No | Whether opted-out recipients should be excluded from delivery. | | scheduleDateTime | string (ISO 8601 datetime) | No | Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. `2025-03-01T14:30:00Z`). If omitted, the message or campaign is sent immediately. | #### Responses **Authentication Error (HTTP 403)** Returned when the API key is invalid or does not have the required permission. ```json { "success": false, "error": { "name": "AuthenticationError", "statusCode": 403 } } ``` **Validation Error (HTTP 400)** Returned when required fields are missing or invalid. ```json { "success": false, "error": { "name": "ValidationError", "statusCode": 400, "object": "Missing Originator object" } } ``` **Success (HTTP 200)** Returned when the message has been successfully accepted for delivery. ```json { "success": true, "record": { "id": "e5815fee-e86e-4fd7-9cad-55444f023bbb", "type": "SingleSMS", "scheduled": "2025-11-10T21:14:04.981Z", "recipientCount": 1 } } ``` A successful response confirms that the message has been queued for delivery. SMS delivery itself is handled asynchronously. # Send Batch SMS Messages Send SMS messages to multiple recipients in a single request. This is commonly referred to as sending a **campaign**. Batch messages support: * Multiple recipients * Per-recipient metadata for message personalisation * Optional per-recipient overrides (text and originator) * Mailing list recipients ### `POST` `/send/batch` #### Required Permission ``` create:BatchSMS ``` Your API key must have this permission enabled in order to use this endpoint. ### Message Personalisation You can include **meta fields** for each recipient and reference them within your message using template tags. For example: ``` Hello {{NAME}}, how is the weather in {{CITY}}? ``` Each recipient’s meta object determines how the message is rendered. #### Example Request ```bash curl --location 'https:///send/batch' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "recipients": [ { "recipient": "4479000000001", "reference": "aaa", "meta": { "NAME": "John", "CITY": "London" } }, { "recipient": "4479000000002", "reference": "bbb", "meta": { "NAME": "Jack", "CITY": "Dublin" } }, { "recipient": "4479000000003", "reference": "ccc", "originator": "CustomOrigin", "text": "Hello Michael. How are you?" }, { "recipient": "3392287d-7a79-4789-9ef8-7dc174836688", "meta": { "type": "mailinglist" } } ], "text": "Hello {{NAME}}, how is the weather in {{CITY}}?", "originator": "test", "name": "My Campaign", "shortenUrls": true, "excludeDuplicates": true, "excludeOptOuts": true, "spreadHours": 0 }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Request Parameters | Field | Type | Required | Description | | ---------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | Yes | The SMS message content. | | originator | string | Yes | The sender ID displayed on the recipient’s handset. | | recipient | string | Yes | The destination phone number in international format. | | shortenUrls | boolean | No | Whether URLs in the message should be automatically shortened. | | excludeOptouts | boolean | No | Whether opted-out recipients should be excluded from delivery. | | spreadHours | number | No | Spread message delivery evenly over the specified number of hours. | | scheduleDateTime | string (ISO 8601 datetime) | No | Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. `2025-03-01T14:30:00Z`). If omitted, the message or campaign is sent immediately. | #### Responses **Authentication Error (HTTP 403)** Returned when the API key is invalid or does not have the required permission. ```json { "success": false, "error": { "name": "AuthenticationError", "statusCode": 403 } } ``` **Validation Error (HTTP 400)** Returned if the API key is invalid or missing the required permission. **Success (HTTP 200)** Returned when the campaign has been successfully accepted for delivery. ```json { "success": true, "record": { "id": "8af60d9-de7f-45ce-97f1-35a91b45277", "type": "BatchSMS", "scheduled": "2025-11-10T21:12:32.786Z", "recipientCount": 5 } } ``` A successful response confirms that the campaign has been queued. Message delivery and delivery receipts are processed asynchronously. # Send Campaign With Daily Limits Campaign daily limits allow you to restrict how many messages can be accepted for a specific batch campaign within a single day. This is useful for throttling large sends or enforcing volume controls. If the daily limit is reached, any further requests for that campaign on the same day will be rejected. If no daily limit is required, use the standard [Batch SMS endpoint](/sending-sms/send-batch-sms-messages) instead. ### `POST` `/send/campaign/limited/{dailyLimit}` Replace {dailyLimit} with the maximum number of messages that may be accepted per day for the campaign. #### Required Permission ``` create:BatchSMS ``` Your API key must have this permission enabled to use this endpoint. ### Example Request ```bash curl --location 'https:///send/campaign/limited/5' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "name": "test", "recipients": [ { "recipient": "447000000000", "reference": "aaa", "meta": { "NAME": "John" } }, { "recipient": "447000000001", "reference": "bbb", "meta": { "NAME": "Mike" } } ], "text": "Hello {{NAME}}", "originator": "test", "shortenUrls": false, "excludeDuplicates": false, "excludeOptOuts": true, "spreadHours": 0 }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} ### How Daily Limits Work * The `{dailyLimit}` value defines the maximum number of messages that can be **accepted** for the campaign per day. * The limit is evaluated per campaign name. * Limits reset automatically at **midnight UTC**. * Messages that would exceed the daily limit are rejected and not queued for delivery. #### Request Parameters | Field | Type | Required | Description | | ---------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | Yes | The SMS message content. | | originator | string | Yes | The sender ID displayed on the recipient’s handset. | | recipient | string | Yes | The destination phone number in international format. | | shortenUrls | boolean | No | Whether URLs in the message should be automatically shortened. | | excludeOptouts | boolean | No | Whether opted-out recipients should be excluded from delivery. | | spreadHours | number | No | Spread message delivery evenly over the specified number of hours. | | scheduleDateTime | string (ISO 8601 datetime) | No | Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. `2025-03-01T14:30:00Z`). If omitted, the message or campaign is sent immediately. | #### Success (HTTP 200) Returned when the campaign is accepted and within the configured daily limit. The response format matches a standard Batch SMS response. #### Daily Limit Reached (HTTP 429) Returned when the campaign has reached its daily message limit. ```json { "success": false, "campaignName": "test", "dailyLimit": 6, "sentToday": 5, "error": "Daily limit of 6 reached for 'test'!" } ``` This response indicates that no additional messages were accepted for the campaign on the current day. {% hint style="info" %} Daily limits apply only to message **acceptance**, not delivery completion. {% endhint %} # Send A Campaign Based On Template Template-based campaigns allow you to send SMS messages using a **predefined template** stored in your Mobivate account. Messages can be sent to: * Individual recipients * Mailing lists / contact groups * Or a combination of both Per-recipient metadata and language selection are supported for dynamic message rendering. ### `POST` `/send/template` #### Required Permission ``` create:TemplateSMS ``` Your API key must have this permission enabled to use this endpoint. ### How Templates Work Templates are created and managed within the Mobivate platform. Each template can contain placeholders (for example `{{NAME}}`, `{{CITY}}`) which are populated using recipient `meta` fields at send time. If a template supports multiple languages, the `language` field can be supplied per recipient to control which version is used. #### Example Request ```bash curl --location 'https:///send/template' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "recipients": [ { "recipient": "3392287d-7a79-4789-9ef8-7dc174836688", "meta": { "type": "mailinglist" } }, { "recipient": "3379000000001", "reference": "f1", "language": "FR", "meta": { "NAME": "John", "CITY": "Paris" } }, { "recipient": "4979000000001", "reference": "d1", "language": "DE", "meta": { "NAME": "John", "CITY": "Munich" } } ], "templateID": "aaaaaaa-bbbbbbbb-cccccc-ddddddd-eee" }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} This endpoint behaves similarly to [batch messaging](/sending-sms/send-batch-sms-messages) but uses a predefined message template stored in your account. #### Request Parameters | Field | Type | Required | Description | | ---------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | templateID | string | Yes | The unique identifier of the message template you want to use for this request. | | recipients | array | Yes | An array of recipient objects. Each object defines a destination and optional metadata. See recipient object fields below. | | shortenUrls | boolean | No | Whether URLs in the message should be automatically shortened. | | excludeOptouts | boolean | No | Whether opted-out recipients should be excluded from delivery. | | scheduleDateTime | string (ISO 8601 datetime) | No | Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. `2025-03-01T14:30:00Z`). If omitted, the message or campaign is sent immediately. | #### Recipient Object | Field | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | recipient | string | Yes | The destination phone number in international format. | | reference | string | No | An optional identifier for this recipient, used for tracking in delivery reports. | | language | string | No | Language code (e.g. `FR`, `DE`) to select a specific language variant of the template, if the template supports multiple languages. | | meta | object | No | Key-value pairs used to populate template placeholders (e.g. `NAME`, `CITY`). For mailing list recipients, use `{ "type": "mailinglist" }` to identify the entry as a list rather than an individual number. | #### Responses **Authentication Error (HTTP 403)** Returned when the API key is invalid or does not have the required permission. **Validation Error (HTTP 400)** Returned when required fields are missing or invalid. **Success (HTTP 200)** Returned when the message has been successfully accepted for delivery. ```json { "success": true, "record": { "id": "8af60d9-de7f-45ce-97f1-35a91b45277", "type": "TemplateSMS", "scheduled": "2025-11-10T21:12:32.786Z", "recipientCount": 3 } } ``` A successful response confirms that the campaign has been queued. Message delivery and delivery receipts are handled asynchronously. # Using Alias To Send SMS Alias based messaging allows you to send an SMS to a recipient by referencing an **alias** instead of providing a phone number (MSISDN). For an alias to be deliverable, a contact with the same alias **must already exist** in your address book. If no matching contact is found, the message will not be sent. ### `POST` `/send/alias` #### Required Permission ``` create:AliasSMS ``` Your API key must have this permission enabled to use this endpoint. ### Example Request ```bash curl --location 'https:///send/alias' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "recipients": ["john"], "text": "Hello {{name}} sent at {{time}}", "originator": "test", "excludeDuplicates": true, "excludeOptouts": true, "shortenUrls": true, "name": "Alias Campaign", "spreadHours": 0 }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Request Parameters | Field | Type | Required | Description | | ----------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | recipients | array | Yes | List of aliases to send messages to. | | text | string | Yes | Message content. Supports template placeholders. | | originator | string | Yes | Sender ID displayed on the recipient’s handset. | | name | string | No | Optional campaign name for reporting. | | shortenUrls | boolean | No | Automatically shorten URLs in the message text. | | excludeDuplicates | boolean | No | Prevent duplicate aliases within the request. | | excludeOptouts | boolean | No | Exclude contacts who have opted out. | | spreadHours | number | No | Spread message delivery evenly over the specified number of hours. | | scheduleDateTime | string (ISO 8601 datetime) | No | Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. `2025-03-01T14:30:00Z`). If omitted, the message or campaign is sent immediately. | ### Template Placeholders Alias-based messages support template placeholders in the message text, such as: ```json Hello {{name}} sent at {{time}} ``` Placeholder values are resolved using the contact data stored in your address book. #### Success (HTTP 200) ```json { "success": true, "record": { "id": "8af60d9-de7f-45ce-97f1-35a91b45277", "type": "AliasSMS", "scheduled": "2025-11-10T21:12:32.786Z", "recipientCount": 1 } } ``` A successful response confirms that the message has been queued for delivery. Message delivery and delivery receipts are handled asynchronously. # Introduction To Searching & Pagination Many `GET` endpoints support query parameters for filtering, sorting, and pagination. These include endpoints like [**Message History**](/message-history/search-sent-and-received-messages), [**Contact Lists**](/contact-management/list-contacts), [**Opt-Outs**](/optouts-management/list-opt-outs), and [**Campaigns**](/message-history/list-message-campaigns). | Parameter | Type | Description | | --------- | ------ | --------------------------------------------------------------- | | sortField | string | The field to sort results by (e.g., `created_on`). | | sortDir | string | Direction of sorting: `ASC` (ascending) or `DESC` (descending). | | offset | number | Number of records to skip (for pagination). | | limit | number | Maximum number of records to return per page (e.g., 10). | We recommend that you use these prameters to effectively handle larger datasets. {% hint style="info" %} All endpoints that return lists may support these parameters. Check individual endpoint docs for availability. {% endhint %} # Create New Contact Create a new contact in your address book. Contacts can be referenced later when sending messages using aliases, batch campaigns, or template-based messaging. ### `POST` `/addressbook/contacts` #### Required Permission ``` create:Contacts ``` Your API key must have this permission enabled in order to use this endpoint. ### Example Request ```bash curl --location 'https:///contacts' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "alias": "john", "msisdn": "4479000000001", "groupID": "YOUR_GROUP_ID", "meta": { "NAME": "John", "CITY": "London" } }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Request Parameters | Field | Type | Required | Description | | ------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | alias | string | Yes | Unique identifier for the contact. Used for alias-based messaging. | | msisdn | string | Yes | Phone number in international format. | | meta | object | No | Custom key-value data associated with the contact. Used for message personalisation. | | groupID | string | No | The ID of an existing contact group. If provided, the contact will automatically be added to this group when created. If omitted, the contact is created without being assigned to a group. | {% hint style="info" %} **Note:** `groupId` is optional. The value must be the ID of an existing contact group. If an invalid group ID is supplied, the request will return a validation error. {% endhint %} #### Responses #### Success (HTTP 200) Returned when the contact is successfully created. ```json { "success": true, "record": { "id": "3392287d-7a79-4789-9ef8-7dc174836688", "alias": "john", "msisdn": "4479000000001", "created_on": "2025-11-10T20:15:12.000Z" } } ``` #### Validation Error (HTTP 400) Returned when required fields are missing or invalid. ```json { "success": false, "error": { "name": "ValidationError", "statusCode": 400, "message": "Alias is required" } } ``` {% hint style="warning" %} **Aliases** must be unique within your address book. {% endhint %} # List Contacts Retrieve a paginated list of contacts from your address book. This endpoint supports sorting and pagination to help you efficiently browse or sync contact data. {% hint style="info" %} This endpoint is **read-only** and does not modify contact data. {% endhint %} ### `GET` `/addressbook/contacts` #### Required Permission ``` read:Contacts ``` Your API key must have this permission enabled in order to use this endpoint. ### Example Request ```bash curl --location 'https:///addressbook/contacts?sortField=created_on&sortDir=DESC&offset=0&limit=10' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Request Parameters | Field | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------- | | sortField | string | No | Field to sort by (e.g. `created_on`). | | sortDir | string | No | Sort direction: `ASC` or `DESC`. | | offset | number | No | Number of records to skip (for pagination). | | limit | number | No | Maximum number of records to return. | #### Responses #### Success (HTTP 200) ```json { "success": true, "records": [ { "id": "3392287d-7a79-4789-9ef8-7dc174836688", "alias": "john", "msisdn": "4479000000001", "created_on": "2025-11-10T20:15:12.000Z" } ], "offset": 0, "limit": 10, "total": 128 } ``` The response includes: * A list of contact records * Pagination metadata for navigating large address books {% hint style="success" %} This endpoint supports sorting and pagination. See [Search & Pagination Parameters](/search-and-pagination-parameters/introduction-to-searching-and-pagination) for details. {% endhint %} # Update Contact Update an existing contact in your address book. This endpoint allows you to modify contact details such as the phone number or associated metadata. ### `POST` `/addressbook/contacts/{contact_id}` Replace `{contact_id}` with the associated contact ID of the record you want to update. #### Required Permission ``` update:Contacts ``` Your API key must have this permission enabled in order to use this endpoint. ### Example Request ```bash curl --location 'https:///addressbook/contacts/3392287d-7a79-4789-9ef8-7dc174836688' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "msisdn": "55555555555", "alias": "john", "meta": { "NAME": "John Doe" } }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Request Parameters Path Parameters | Field | Type | Required | Description | | ----------- | ------ | -------- | ----------------------------------------------------------- | | contact\_id | string | Yes | The associated contact ID of the record you want to update. | Body Parameters | Field | Type | Required | Description | | ------ | ------ | -------- | --------------------------------------------- | | msisdn | string | No | Updated phone number in international format. | | alias | string | No | Updated alias for the contact. | | meta | object | No | Updated metadata associated with the contact. | #### Responses #### Success (HTTP 200) Returned when the contact is successfully updated. ```json { "success": true, "record": { "id": "3392287d-7a79-4789-9ef8-7dc174836688", "alias": "john", "msisdn": "55555555555", "updated_on": "2025-11-10T20:45:30.000Z" } } ``` #### Validation Error (HTTP 400) Returned when the specified contact does not exist. ```json { "success": false, "error": { "name": "NotFoundError", "statusCode": 404, "message": "Contact not found" } } ``` {% hint style="info" %} Updating a contact does not affect historical message records. {% endhint %} # Delete a Contact Delete an existing contact from your address book. Once deleted, the contact can no longer be used for alias-based messaging or campaigns. ### `DELETE` `/addressbook/contacts/{contact_id}` Replace `{contact_id}` with the associated contact ID of the record you want to delete. #### Required Permission ``` delete:Contacts ``` Your API key must have this permission enabled in order to use this endpoint. ### Example Request ```bash curl --request DELETE 'https:///addressbook/contacts/3392287d-7a79-4789-9ef8-7dc174836688' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Responses #### Success (HTTP 200) Returned when the contact has been successfully deleted. ```json { "success": true } ``` #### Not Found (HTTP 404) Returned when the specified contact does not exist. ```json { "success": false, "error": { "name": "NotFoundError", "statusCode": 404, "message": "Contact not found" } } ``` {% hint style="danger" %} Please remember that deleting a contact is **permanent** and cannot be undone. If you plan to re-add the contact later, you must create it again. {% endhint %} # Create a Group Create a new contact group in your address book. Groups (also referred to as mailing lists) can be used as recipients when sending batch, template, or campaign-based messages. ### `POST` `/addressbook/groups` #### Required Permission ``` create:Groups ``` Your API key must have this permission enabled in order to use this endpoint. ### Example Request ```bash curl --location 'https:///addressbook/groups' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data-urlencode 'name=test1' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} ### Request Parameters #### Body Parameters | Field | Type | Required | Description | | ----- | ------ | -------- | ------------------------------------------------------------------- | | name | string | Yes | Name of the contact group. Must be unique within your address book. | ### Responses #### Success (HTTP 200) Returned when the group is successfully created. ```json { "success": true, "record": { "id": "3392287d-7a79-4789-9ef8-7dc174836688", "name": "test1", "created_on": "2025-11-10T21:30:45.000Z" } } ``` #### Validation Error (HTTP 400) Returned when the request is invalid, such as when the group name is missing or already exists. ```json { "success": false, "error": { "name": "ValidationError", "statusCode": 400, "message": "Group name already exists" } } ``` # List Groups Retrieve a paginated list of contact groups (mailing lists) from your address book. This endpoint supports sorting and pagination to help manage large numbers of groups. ### `GET` `/addressbook/groups` #### Required Permission ``` read:Groups ``` Your API key must have this permission enabled in order to use this endpoint. ### Example Request ```bash curl --location 'https:///addressbook/groups?sortField=created_on&sortDir=DESC&offset=0&limit=10' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} ### Request Parameters | Field | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------- | | sortField | string | No | Field to sort by (e.g. `created_on`). | | sortDir | string | No | Sort direction: `ASC` or `DESC`. | | offset | number | No | Number of records to skip (for pagination). | | limit | number | No | Maximum number of records to return. | ### Responses #### Success (HTTP 200) ```json { "success": true, "records": [ { "id": "3392287d-7a79-4789-9ef8-7dc174836688", "name": "test1", "created_on": "2025-11-10T21:30:45.000Z" } ], "offset": 0, "limit": 10, "total": 12 } ``` {% hint style="success" %} This endpoint supports sorting and pagination. See [Search & Pagination Parameters](/search-and-pagination-parameters/introduction-to-searching-and-pagination) for details. {% endhint %} # Delete a Group Delete an existing contact group (mailing list) from your address book. Once deleted, the group and its associations cannot be recovered. ### `DELETE` `/addressbook/groups/{groupID}` #### Required Permission ``` delete:Groups ``` Your API key must have this permission enabled in order to use this endpoint. ### Path Parameters | Field | Type | Required | Description | | ------- | ------ | -------- | --------------------------------------------- | | groupID | string | Yes | The unique ID of the contact group to delete. | ### Example Request ```bash curl --location --request DELETE 'https:///addressbook/groups/aaaa-bbbb-ddddd' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key and `groupID` with the ID of the group you want to delete. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Responses #### Success (HTTP 200) ```json { "success": true } ``` #### Error Responses **Authentication / Authorization Error (HTTP 403)** Returned if the API key does not have the `delete:Groups` permission. ```json { "success": false, "error": "Not authorized to delete groups" } ``` **Group Not Found (HTTP 404)** Returned if the specified group ID does not exist. ```json { "success": false, "error": "Group not found" } ``` {% hint style="danger" %} This operation is **permanent** and cannot be undone. {% endhint %} # Create an Opt-Out Add a phone number to the opt-out list. Once opted out, the recipient will no longer receive messages. ### `POST` `/addressbook/optouts` #### Required Permission ``` create:Optouts ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///addressbook/optouts' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "msisdn": "55555555555" }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Request Parameters | Field | Type | Required | Description | | -------- | ------ | -------- | ----------------------------------------------- | | `msisdn` | string | Yes | Phone number to opt out (international format). | #### Success Response (HTTP 200) ```json { "success": true } ``` # List Opt-Outs Retrieve a paginated list of opt-out records from your address book. ### `GET` `/addressbook/optouts` #### Required Permission ``` read:Optouts ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///addressbook/optouts?offset=0&limit=10' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------- | | offset | number | No | Number of records to skip (pagination). | | limit | number | No | Maximum number of records to return. | #### Success Response (HTTP 200) ```json { "success": true, "records": [ { "msisdn": "55555555555", "created_on": "2025-11-10T21:45:12.000Z" } ], "offset": 0, "limit": 10, "total": 3 } ``` {% hint style="success" %} This endpoint supports sorting and pagination. See [Search & Pagination Parameters](/search-and-pagination-parameters/introduction-to-searching-and-pagination) for details. {% endhint %} # Delete an Opt-Out Remove a phone number from the opt-out list, allowing messages to be sent to the recipient again. ### `DELETE` `/addressbook/optouts/{msisdn}` Replace `{msisdn}` with the phone number you want to remove from the opt-out list. #### Required Permission ``` delete:Optouts ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location --request DELETE 'https:///addressbook/optouts/55555555555' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Success Response (HTTP 200) ```json { "success": true } ``` #### Not Found (HTTP 404) Returned if the MSISDN is not present in the opt-out list. ```json { "success": false, "error": "Opt-out record not found" } ``` If you want to send to Opted-out phone numbers you can override this by using `excludeOptOuts`, where supported. {% hint style="info" %} Opt-outs are applied **globally** across all messaging endpoints. {% endhint %} # Search Sent and Received Messages Retrieve a list of messages within a specific date range. Supports filtering by from/to dates. ### `GET` `/messages/history` #### Required Permission ``` read:SingleSMS ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///messages/history?fromDate=2025-10-01&toDate=2025-10-11' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Query Parameters | Field | Type | Required | Description | | -------- | ------------------- | -------- | ------------------------------------------- | | fromDate | string (YYYY-MM-DD) | Yes | Start date of the search range. | | toDate | string (YYYY-MM-DD) | Yes | End date of the search range. | | offset | number | No | Number of records to skip (for pagination). | | limit | number | No | Maximum number of records to return. | #### Response (HTTP 200) ```json { "success": true, "records": [ { "id": "e5815fe-e86-4fd7-9cad-4944f023", "recipient": "4479000000001", "originator": "test", "text": "Hello World", "status": "Delivered", "sent_on": "2025-10-01T12:34:56.000Z" } ], "offset": 0, "limit": 10, "total": 42 } ``` {% hint style="success" %} This endpoint supports sorting and pagination. See [Search & Pagination Parameters](/search-and-pagination-parameters/introduction-to-searching-and-pagination) for details. {% endhint %} # Get Message Summary Retrieve a list of messages within a specific date range. Supports filtering by from/to dates. ### `GET` `/messages/summary` #### Required Permission ``` read:Dashboard ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///messages/summary?fromDate=2025-01-01&toDate=2025-03-01' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------------------- | -------- | --------------------------------- | | fromDate | string (YYYY-MM-DD) | Yes | Start date for the summary range. | | toDate | string (YYYY-MM-DD) | Yes | End date for the summary range. | ### Response (HTTP 200) ```json { "success": true, "summary": { "totalSent": 1000, "totalDelivered": 980, "totalFailed": 20, "totalOptedOut": 5, "totalPending": 10 } } ``` #### Response Fields | Field | Type | Description | | -------------- | ------ | --------------------------------------- | | totalSent | number | Total messages submitted in the period. | | totalDelivered | number | Total messages successfully delivered. | | totalFailed | number | Total messages that failed to deliver. | | totalOptedOut | number | Total messages blocked due to opt-outs. | | totalPending | number | Messages still awaiting delivery. | {% hint style="info" %} Date filters (`fromDate` and `toDate`) must be in `YYYY-MM-DD` format. {% endhint %} {% hint style="success" %} This endpoint supports sorting and pagination. See [Search & Pagination Parameters](/search-and-pagination-parameters/introduction-to-searching-and-pagination) for details. {% endhint %} # List Message Campaigns Retrieve a list of messages within a specific date range. Supports filtering by from/to dates. ### `GET` `/messages/campaigns` #### Required Permission ``` read:BatchSMS ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///messages/campaigns?fromDate=2025-01-01&toDate=2025-03-01' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Response (HTTP 200) ```json { "success": true, "records": [ { "id": "8af60d9-de7f-45ce-7f13-5a91bb45277", "name": "Test Campaign", "recipientCount": 10, "scheduled": "2025-01-05T10:00:00.000Z", "status": "Completed" } ], "offset": 0, "limit": 10, "total": 5 } ``` {% hint style="success" %} This endpoint supports sorting and pagination. See [Search & Pagination Parameters](/search-and-pagination-parameters/introduction-to-searching-and-pagination) for details. {% endhint %} # List Available Message Templates Retrieve a list of messages within a specific date range. Supports filtering by from/to dates. ### `GET` `/message-templates` #### Required Permission ``` read:MessageTemplates ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///message-templates' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Response (HTTP 200) ```json { "success": true, "records": [ { "id": "aaaaaaa-bbbbbbbb-cccccc-ddddddd-eee", "name": "Welcome Template", "text": "Hello {{NAME}}, welcome to our service!", "created_on": "2025-01-01T12:00:00.000Z" } ] } ``` {% hint style="info" %} We recommend using date filters to efficiently retrieve historical messages and campaign data. {% endhint %} # Get Current Wallet Balance The Wallet API allows you to monitor your account balance, track transactions, and enable or disable automatic top-ups. These endpoints help you manage funds used for sending SMS messages. Retrieve the current balance of your account. ### `GET` `/wallet` #### Required Permission ``` read:UserWallet ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///wallet' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Response (HTTP 200) ```json { "success": true, "balance": 42.50, "currency": "USD" } ``` # Get Wallet Transactions Retrieve a list of recent wallet transactions, including debits and credits. ### `GET` `/wallet/transactions` #### Required Permission ``` read:UserWalletDailyTransactions ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///wallet/transactions' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Response (HTTP 200) ```json { "success": true, "transactions": [ { "id": "txn_001", "type": "credit", "amount": 50.00, "currency": "USD", "created_on": "2025-02-01T12:00:00.000Z" }, { "id": "txn_002", "type": "debit", "amount": 10.00, "currency": "USD", "created_on": "2025-02-02T08:45:00.000Z" } ] } ``` # Enable Auto-Topup Automatically add funds to your wallet when the balance falls below a specified threshold. Requires that a billing method is already set in the user interface. ### `POST` `/wallet/auto-topup/enable` #### Required Permission ``` create:UserAutoTopUp ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///wallet/auto-topup/enable' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "amount": 15, "threshold": 10 }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------- | | amount | number | Yes | Amount to top-up automatically. | | threshold | number | Yes | Minimum balance that triggers the top-up. | #### Response (HTTP 200) ```json { "success": true, "autoTopupEnabled": true, "amount": 15, "threshold": 10 } ``` {% hint style="info" %} **Auto-topup** requires a valid billing method set in the user interface. {% endhint %} # Disable Auto-Topup Disable automatic top-ups for your wallet. ### `POST` `/wallet/auto-topup/disable` #### Required Permission ``` delete:UserAutoTopUp ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location --request POST 'https:///wallet/auto-topup/disable' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} #### Response (HTTP 200) ```json { "success": true, "autoTopupEnabled": false } ``` # HLR (Number Lookup) Perform a **synchronous HLR (Home Location Register) lookup** to get detailed information about one or more mobile numbers. This is useful for verifying number validity, detecting ported numbers, and understanding the network associated with each recipient. ### `GET` `/hlr` #### Required Permission ``` create:HLR ``` Your API key must have this permission enabled in order to use this endpoint. #### Example Request ```bash curl --location 'https:///hlr?lookup=4400000000000,4400000000001,4400000000002' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request. {% endhint %} ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------------------------------------- | | lookup | string | Yes | Comma-separated list of MSISDNs (phone numbers in international format) to verify. | #### Response (HTTP 200) ```json { "success": true, "batchID": "0c040d34-e2a-460a-97dd-66ffc235a7", "results": [ { "to": "4400000000000", "mccMnc": "23410", "imsi": "234100000000000", "originalNetwork": { "networkName": "MNO - BT - Everything Everywhere Limited", "networkPrefix": "79324", "countryName": "United Kingdom", "countryPrefix": "44", "networkId": 791 }, "ported": true, "portedNetwork": { "networkName": "MNO - Virgin Media O2 (Telefonica UK Ltd)", "networkPrefix": "76020", "countryName": "United Kingdom", "countryPrefix": "44", "networkId": 785 }, "status": { "groupId": 3, "groupName": "DELIVERED", "id": 5, "name": "DELIVERED_TO_HANDSET", "description": "Message delivered to handset" }, "error": { "groupId": 0, "groupName": "OK", "id": 0, "name": "NO_ERROR", "description": "No Error", "permanent": false } } ] } ``` ### Response Fields | Field | Type | Description | | --------------- | ------- | --------------------------------------------------------------- | | batchID | string | Unique ID for this HLR lookup batch. | | results | array | Array of objects, one per number looked up. | | to | string | The phone number queried. | | mccMnc | string | Mobile Country Code & Mobile Network Code. | | imsi | string | International Mobile Subscriber Identity. | | originalNetwork | object | Details about the number’s original network. | | ported | boolean | Indicates if the number has been ported to a different network. | | portedNetwork | object | Details of the network the number is ported to (if applicable). | | status | object | Current delivery/status group of the number. | | error | object | Any errors encountered during the lookup. | {% hint style="info" %} You can lookup multiple MSISDNs at once using a **comma separated list**. {% endhint %} # Configuring SMPP Connection Mobivate BulkSMS supports SMPP connections for high-throughput and low-latency message delivery. ### `POST` `/integrations/smpp` ### Authentication SMPP credentials are managed separately from your API key and must be configured before connecting. You have two options: **Option 1: Mobivate Dashboard** 1. Log into your [Mobivate](https://www.hub.mobivate.com/) account. 2. Click the **cog icon** in the top-right corner of the page. 3. Click on **User Profile.** 4. Navigate to the **Credentials** tab. 5. Click **SMPP**. 6. Configure your **SMPP Credentials** directly in the UI. **Option 2: Integrations API** Use our API endpoint to programmatically create or manage your SMPP connection: Your API key must be included in the request. The request body accepts a `parameters` object and an optional `secret` object: #### Parameters Object | Field | Type | Required | Description | | ------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | enabled | boolean | Yes | Whether the SMPP bind is active. Set to `false` to disable the connection (takes effect within 30 seconds and closes any active binds). | | allowed\_ips | string | Yes | Comma-separated list of whitelisted IP ranges in CIDR notation. Use `0.0.0.0/0` to allow connections from anywhere. | | dailyLimit | integer or null | Yes | Maximum number of messages per day. Set to `null` for no limit. | #### Secret Object (Optional) | Field | Type | Description | | -------- | -------------- | ------------------------------------------------------------------------------------------ | | systemID | string or null | Provide a value to set or rotate the username/system ID. Set to `null` to leave unchanged. | | password | string or null | Provide a value to set or rotate the password. Set to `null` to leave unchanged. | ### Example Requests Generate new credentials and allow connections from anywhere with no daily limit: ```bash curl --location 'https:///integrations/smpp' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "parameters": { "enabled": true, "allowed_ips": "0.0.0.0/0", "dailyLimit": null }, "secret": { "systemID": "aaaaaaaaaaaaaa", "password": null } }' ``` Rotate password only: ```bash curl --location 'https:///integrations/smpp' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "parameters": { "enabled": true, "allowed_ips": "0.0.0.0/0", "dailyLimit": null }, "secret": { "systemID": null, "password": "0plt0jn2" } }' ``` Disable the bind, restrict to specific IPs, and set a daily limit: ```bash curl --location 'https:///integrations/smpp' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "parameters": { "enabled": false, "allowed_ips": "1.2.3.4/32,5.5.5.5/32", "dailyLimit": 400 } }' ``` Replace `YOUR_API_KEY` with your API key. {% hint style="info" %} The hostname shown in this documentation uses a **sample hostname**. The production SMPP hostname is provided by our team upon request. {% endhint %} ### Required Permissions Your API key **must** have the following permission enabled: ``` create:SingleSMS ``` Without this permission, SMPP message submission will be rejected. ### SMPP Connection Details Use the following connection settings when configuring your SMPP client: | Setting | Value | | -------- | ----------- | | Hostname | \ | | Port | 2775 | {% hint style="info" %} The hostname shown in this documentation uses a **sample hostname**. The production SMPP hostname is provided by our team upon request. {% endhint %} ### Security Recommendations We strongly recommend restricting access by whitelisting specific IP ranges in your SMPP configuration rather than using `0.0.0.0/0` in production environments. IP restrictions can be configured when managing your API keys in the Mobivate dashboard. {% hint style="warning" %} Treat your SMPP credentials with the same care as your API keys. Do not expose credentials in client-side code or public repositories. {% endhint %} # Frequently Asked Questions This document will go over frequently asked questions. Here are a few frequently asked questions from our customers.
Can I send Unicode messages? Yes, unicode message sending is supported. Make sure you include the correct header when **POST**ing data (`application/json; charset=utf-8`). **Warning:** Sending unicode characters can affect message cost.
Are Emojis supported in the message text? **Yes**, Emojis are supported. Emojis are sent as unicode characters, please refer to our message length calculator to see how emojis affect your messages. **Warning:** Sending unicode characters can affect message cost.
What is SMS Originator / Sender ID? The SMS Originator (or Sender ID) is the text display name that you see at the top of your phone screen and is used to identify who sent the message. The SMS sender ID is simply who a text message is from.
What is the maximum length of the Originator / Sender ID? The maximum length depends on the characters included in the originator:\ **NUMERIC** - If the originator contains only numbers, maximum length is 15 characters. For example - `"123456"`.\ **ALPHA-NUMERIC** - If the originator contains letters, maximum length is 11 characters. For example - `"Brand", "Brand 123"` **Warning:** Originators that exceed the maximum length will be trimmed.
Are Emojis supported in the message Originator / Sender ID? No, Emojis are not supported or allowed in message Originator. **Warning:** Originators that contain Emojis will be rejected by the carriers.
Can recipients reply to a message if the Originator contains letters? No, if you set the Originator to ALPHA-NUMERIC recipients will not be able to reply to the text.
Can the Originator contain spaces? The Originator can only contain letters or numbers, spaces are not permitted. No other non-GSM characters are permitted either, Unicode characters are not permitted.
Can you include links in an SMS? You can include any link in any SMS campaign you would like. However, there are a few concerns to consider: \- Links may take up much of the 160 character limit for SMS. If you include a link and text, it may result in two SMS messages instead of just one.\ \- Companies often use link shorteners to limit the character count impact of a link. However, if sending a shortened link through a long code, carriers may block or deny the message, as they may be suspicious of the link redirect.\ \- Consider using our URL Shortener to automatically shorten long URLs and provide you with click tracking.
What are the best sending practices to avoid spam detection for SMS? You can include any link in any SMS campaign you would like. However, there are a few concerns to consider: \- Make sure opt-in and opt-out instructions are clear.\ \- Ensure you (the brand) have a relationship with the customer.\ \- Make sure the content is relevant to the relationship and what the user has opted-in to receive.
# Creating a New API Key This document will go over how to generate/create a new API key. ### `POST` `/auth/createkey` Create/generate a new API key for your Mobivate account. {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "https://api.mobivatebulksms.com/auth/createkey" \ -H 'Content-Type: application/json' \ -d '{ "username": "first.last@email.com", "password": "your-pass"}' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', } json_data = { 'username': 'first.last@email.com', 'password': 'your-pass', } response = requests.post('https://api.mobivatebulksms.com/auth/createkey', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "username": "first.last@email.com", "password": "your-pass"}' #response = requests.post('https://api.mobivatebulksms.com/auth/createkey', headers=headers, data=data) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `No Auth` | **Body**
NameTypeRequired?Description
usernamestringYesYour username used to login.
passwordstringYesYour password used to login.
**Response** We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). {% tabs %} {% tab title="200" %} ```json { "apiKey":"abcd1234-9922-abcd-1234-abcd1234abcd" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Invalid Credentials" } ``` {% endtab %} {% endtabs %} Upon a successful send request, our server will respond with a 200 (success) HTTP response code, and you will be provided with an API Key. The **API Key** will be used in subsequent calls to the API. {% hint style="warning" %} **Please note**: A successful call to this endpoint will revoke your existing API Key! {% endhint %} To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Get API Key This document will detail how to obtain an existing API key. ### `POST` `/auth/getkey` Get your currently available api-key from your Mobivate account. {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "https://api.mobivatebulksms.com/auth/getkey" \ -H 'Content-Type: application/json' \ -d '{ "username": "[USERNAME]", "password": "[PASSWORD]"}' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', } json_data = { 'username': '[USERNAME]', 'password': '[PASSWORD]', } response = requests.post('https://api.mobivatebulksms.com/auth/getkey', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "username": "[USERNAME]", "password": "[PASSWORD]"}' #response = requests.post('https://api.mobivatebulksms.com/auth/getkey', headers=headers, data=data) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `No Auth` | **Body**
NameTypeRequired?Description
usernamestringYesYour username used to login.
passwordstringYesYour password used to login.
**Response** We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). {% tabs %} {% tab title="200" %} ```json { "apiKey":"abcd1234-9922-abcd-1234-abcd1234abcd" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Invalid Credentials" } ``` {% endtab %} {% endtabs %} Upon a successful send request, our server will respond with a 200 (success) HTTP response code, and you will be provided with an API Key. The **API Key** will be used in subsequent calls to the API. To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Test API Key This document will detail how to test your existing API key. ### `GET` `/auth/test` Test your existing Mobivate API key to ensure it's ready for API use. {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/auth/test" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } response = requests.get('https://api.mobivatebulksms.com/auth/test', headers=headers) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer ` | **Body** {% hint style="success" %} There are no **Arguments** required to test your existing API key. {% endhint %} **Response** We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). {% tabs %} {% tab title="200" %} ```json { "message":"API Key is valid" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Getting started with Integration This document will describe how to get started with our API. ### Basic Integration This documentation will guide you through the process of integrating with our API, from obtaining API credentials to constructing HTTP requests and handling responses. With our comprehensive documentation and examples, you'll be up and running in no time, sending SMS messages to your users' mobile devices effortlessly. Let's dive in and unlock the full potential of SMS communication in your application: 1. Let's get started by [creating your API key](/archived-docs/creating-a-new-api-key). 2. If you'd like to receive [Delivery Receipts](/archived-docs/registering-webhooks/delivery-receipt-notification) , register your [Webhook listener](/archived-docs/registering-webhooks) endpoint. 3. Send messages to [Single Recipients](/archived-docs/send-single-sms-message) , or scale up your outreach by [Sending Batches](/archived-docs/send-batch-sms-messages) of up to 1,000 messages per request. ### Authentication Authentication to the API is performed via **Bearer** keys. Once you have created your API Key, it should be provided along with every request. For example, use the following in **CURL** requests: ``` -H "Authorization: Bearer [API Key]" ``` ### Sending Messages SMS message delivery operates as an asynchronous process within our system. Upon submitting a message to our platform, we will acknowledge receiving the message and asynchronously deliver it to the handset. If you registered for Delivery Receipt notifications, you will receive those to your specified webhook endpoint as they arrive in our system. It is recommended that you store those receipts for asynchronous processing on your end.

BulkSMS API usage overview

{% hint style="warning" %} **Please note:** All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. **Keep your API Keys secure!** Remember not to share your keys in publicly accessible areas such as client-side code or a public Git repository. {% endhint %} # Registering Webhooks This page will document how to Register webhooks for our API to use. Receive Web Hook notifications, register your webhook endpoint. Please provide a publicly accessible HTTPS URL to your webhook endpoint. ### `POST` `/webhooks/receipt` Used to register for [Delivery Receipt](/archived-docs/registering-webhooks/delivery-receipt-notification) notifications. {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "https://api.mobivatebulksms.com/webhooks/receipt" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "url": "https://your.domain.com/endpoint" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'url': 'https://your.domain.com/endpoint', } response = requests.post('https://api.mobivatebulksms.com/webhooks/receipt', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "url": "https://your.domain.com/endpoint" }' #response = requests.post('https://api.mobivatebulksms.com/webhooks/receipt', headers=headers, data=data) ``` {% endtab %} {% endtabs %} ### Incoming Messages ### `POST` `/webhooks/incoming` Use to register for [Incoming Message](/archived-docs/registering-webhooks/incoming-message-notification) notifications. {% tabs %} {% tab title="Curl" %} ```hsts /curl -X POST \ "https://api.mobivatebulksms.com/webhooks/incoming" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "url": "https://your.domain.com/endpoint" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'url': 'https://your.domain.com/endpoint', } response = requests.post('https://api.mobivatebulksms.com/webhooks/incoming', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "url": "https://your.domain.com/endpoint" }' #response = requests.post('https://api.mobivatebulksms.com/webhooks/incoming', headers=headers, data=data) ``` {% endtab %} {% endtabs %} ### Short URL Clicks ### `POST` `/webhooks/click` Use to register for [Short URL Click](/archived-docs/registering-webhooks/short-url-click-notification) notifications. {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "https://api.mobivatebulksms.com/webhooks/click" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "url": "https://your.domain.com/endpoint" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'url': 'https://your.domain.com/endpoint', } response = requests.post('https://api.mobivatebulksms.com/webhooks/click', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "url": "https://your.domain.com/endpoint" }' #response = requests.post('https://api.mobivatebulksms.com/webhooks/click', headers=headers, data=data) ``` {% endtab %} {% endtabs %} **Headers** | Header | Value | | ------------- | ----------------- | | Content-Type | application/json | | Authorization | Bearer \[API Key] | **Body**
NameTypeRequired?Description
urlstringYesURL to receive Delivery Receipt notifications.
**Response** We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). {% tabs %} {% tab title="200" %} ```json { "message":"Webhook updated successfully" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Delivery Receipt Notification This document will go over how to receive Delivery Receipt notifications via API. When the status of a message changes, a notification will be **POSTed** to the specified webhook URL. ### Headers | Header | Value | | ------------ | ---------------- | | Content-Type | application/json | ### Arguments
NameTypeDescription
deliveryMessageIdstringSent Message Id.
batchIdstringBatch ID of the message.
clientReferencestringClient message reference.
createddatetimeDate/Time receipt was received.
statusstringMessage status, see list of possible statuses.
statusCodeintegerMessage status in numeric value.
partsintegerNumber of parts in the message.
hlrobjectHLR Data, see HLR documentation.
### Examples {% tabs %} {% tab title="Payload" %} ```json { "deliveryMessageId":"9A85B95E0A000A9D2FBD46710388AD54", "batchId":"9A85B9110A000A9D2FBD4671D691C328", "clientReference":null, "created":"2023-07-28T03:23:22.000+00:00", "status":"ACCEPTED", "statusCode":2, "parts":1, "hlr":null } ``` {% endtab %} {% endtabs %} ### Delivery Status List
StatusCodeDescription
DELIVERED1Message successfully delivered to the handset.
ACCEPTED2Message accepted by carrier.
EXPIRED3The SMSC was unable to deliver the message in a specified amount of time (e.g. Phone is turned off).
DELETED4Message has been deleted.
UNDELIVERABLE5The SMS was unable to deliver the message (e.g. the number does not exist).
UNKNOWN6Unknown error occurred.
REJECTED7The message was rejected.
INTERIM_QUEUED8Message has been queued by next tier provider.
INTERIM_ACKNOWLEDGED9Message has been acknowledged by next tier provider.
RETRY10Message delivery will be retried.
FAILED_NACK11Message accepted but not delivered to the handset.
FAILED_NOROUTE12Provider could not route the message.
FAILED_INSUFFICIENT_CREDIT17Your account does not have sufficient credit to send the message.
FAILED_ORIGINATOR_RECIPIENT_EQUAL18Message originator and recipient are the same.
FAILED_RECIPIENT_BLACKLISTED19Recipient has been blacklisted.
FAILED_ORIGINATOR_REJECTED20Invalid message originator.
FAILED_ROUTE_INVALID21The selected Route ID cannot send messages to this recipient.
FAILED_LIMITS_EXCEEDED22Your account has exceeded its allocated limits.
FAILED_EXHAUSTED24Retries exhausted.
FAILED_INTERNAL_ERROR28Message failed to process/send due to internal error.
FAILED_UNKNOWN29Message failed to process/send due to unknown error.
REJECTED_INVALID_ORIGINATOR33Message rejected due to invalid originator.
REJECTED_INVALID_RECIPIENT34Message rejected due to invalid recipient.
REJECTED_INVALID_TEXT36Message rejected due to invalid text.
ERR_CONNECTION_NETWORK40Message failed to send due to connectivity issues.
# Incoming Message Notification This document will go over receiving incoming message notifications via our API. When a Mobile Originated (MO / Incoming) message is received, a notification will be **POSTed** to the specified webhook URL. ### Headers | Header | Value | | ------------ | ---------------- | | Content-Type | application/json | ### Arguments
NameTypeDescription
idstringIncoming Message Id.
originatorstringThe mobile number (MSISDN) which sent the message.
recipientstringThe virtual number or shortcode the message was sent to.
bodystringMessage Text.
createdstringDate/Time message was received.
inReplyTostringID of the message that this was in response to.
logicalMessageIdstringThe Batch ID which this message is associated with.
ownerUserIdstringThe ID of the user which received this message.
### Examples {% tabs %} {% tab title="Payload" %} ```json { "id":"1C9A658F0A931B317B6A53BB42EC3571", "originator":"4400000000", "recipient":"12345", "body":"Incoming Message", "created":"2023-09-01T00:30:36+0000", "inReplyTo":"961AEAEB0A000A9D2FBD4671D07705FE", "logicalMessageId":"6EE262430A931B3127AFD4F044FC0622", "ownerUserId":"94B8CC070A000A9D2FBD467124131CA6" } ``` {% endtab %} {% endtabs %} # Short URL Click Notification This document will go over receiving Short URL click messages notifications via our API. When a recipient clicks on a URL thas has been shortened by the system, a notification will be **POSTed** to the specified webhook URL. ### Headers | Header | Value | | ------------ | ---------------- | | Content-Type | application/json | ### Arguments
NameTypeDescription
messageIdstringIncoming Message Id
mobilestringMessage Originator - The mobile which sent the message..
batchIdstringMessage Recipient - The virtual number or shortcode that received the message.
clientRefstringMessage reference as set by the client.
browserstringDevice browser.
countrystringDetected country based on IP Address.
ipAddressstringIP address of the device.
iso2lstringTwo letter country ISO code (e.g. UK).
osstringDevice operating system.
urlstringThe original (long) URL.
### Examples {% tabs %} {% tab title="Payload" %} ```json { "mobile":"4400001234", "messageId":"9AEC3BB90A000A9D2FBD467178FF6827", "batchId":"9AEC3B590A000A9D2FBD4671C4D151BF", "clientRef":"ref-001", "browser":"Safari", "country":"United Kingdom", "ipAddress":"1.1.1.1", "iso2l":"UK", "os":"Mac OS X", "url":"http://vimeo.com/751393851?autoplay=1" } ``` {% endtab %} {% endtabs %} # Send Single SMS Message This document will describe how to send a singular SMS message using our API. ### `POST` `/send/single` Send a single SMS message to recipient. {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "http://api.mobivatebulksms.com/send/single" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "originator": "Test", "recipient": "44700011122", "body": "This is a test message", "routeId": "mglobal" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'originator': 'Test', 'recipient': '44700011122', 'body': 'This is a test message', 'routeId': 'mglobal', } response = requests.post('http://api.mobivatebulksms.com/send/single', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "originator": "Test", "recipient": "44700011122", "body": "This is a test message", "routeId": "mglobal" }' #response = requests.post('http://api.mobivatebulksms.com/send/single', headers=headers, data=data) ``` {% endtab %} {% endtabs %} #### Send a single SMS message with reference {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "https://api.mobivatebulksms.com/send/single" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "originator": "Test", "recipient": "44700011122", "body": "This is a test message", "routeId": "mglobal", "reference": "my-reference-1234" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'originator': 'Test', 'recipient': '44700011122', 'body': 'This is a test message', 'routeId': 'mglobal', 'reference': 'my-reference-1234', } response = requests.post('https://api.mobivatebulksms.com/send/single', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "originator": "Test", "recipient": "44700011122", "body": "This is a test message", "routeId": "mglobal", "reference": "my-reference-1234" }' #response = requests.post('https://api.mobivatebulksms.com/send/single', headers=headers, data=data) ``` {% endtab %} {% endtabs %} **Send a single SMS message with campaign id** {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "https://api.mobivatebulksms.com/send/single" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "originator": "Test", "recipient": "44700011122", "body": "This is a test message", "routeId": "mglobal", "reference": "myref", "campaignId": "abc-123" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'originator': 'Test', 'recipient': '44700011122', 'body': 'This is a test message', 'routeId': 'mglobal', 'reference': 'myref', 'campaignId': 'abc-123', } response = requests.post('https://api.mobivatebulksms.com/send/single', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "originator": "Test", "recipient": "44700011122", "body": "This is a test message", "routeId": "mglobal", "reference": "myref", "campaignId": "abc-123" }' #response = requests.post('https://api.mobivatebulksms.com/send/single', headers=headers, data=data) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer [API Key]` | **Body**
NameTypeRequired?Description
originatorstringYesOriginator/SenderID for SMS messages (MaxLength - AlphaNumeric: 11, numeric: 15).
recipientstringYesRecipient of SMS Message (Numeric only, MSISDN format inc international prefix).
bodystringYesMessage text.
routeIDstringYesSpecified message route.
campaignIdstringNoAttach message to existing campaignId.
referencestringNoYour reference, will be provided as part of the delivery receipt for correlation.
shortenUrlsbooleanNo

Default: false

If set to true, long urls included in the message will be shortened

**Response** {% tabs %} {% tab title="200" %} ```json { "id":"ef5796ce-e326-4a09-9033-6b457039b1ba", "originator":"Test", "recipient":"44700011122", "body":"This is a test message", "routeId":"mglobal", "reference":null, "campaignId":null } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} To see a full list of SMS Responses and examples [click here](/archived-docs/send-single-sms-message/understanding-sms-response-codes). # Understanding SMS Response Codes This document goes over understanding SMS responses using our API. ### Responses We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success.\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted).\ **5xx** errors indicate an error with ours servers (these are rare). ### Sample Success Response Upon a successful send request, our server will respond with a 200 (success) HTTP response code, and you will be provided with a message record which includes our ID. ```json { "id":"ef5796ce-e326-4a09-9033-6b457039b1ba", "originator":"Test", "recipient":"44700011122", "body":"This is a test message", "routeId":"mglobal", "reference":null, "campaignId":null } ``` ### Sample Error Response ```json { "code":401, "message":"Unauthorized" } ``` ```json { "code":403, "message":"Recipient is opted out: 44XXXXXXXX" } ``` ### Response Codes {% hint style="info" %} To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes) {% endhint %} # Send Batch SMS Messages This document will describe how to send batch SMS messages. Batch messages allows you to send up to 1,000 messages per Batch SMS request. These are useful for large campaigns. ### `POST` `/send/batch` Send batch SMS messages to a number of receipients. {% tabs %} {% tab title="Curl" %} ```json curl -X POST "https://api.mobivatebulksms.com/send/batch" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API KEY]' \ -d '{ "routeId": "mglobal", "scheduleDateTime": "2024-08-01T10:00:00+0200", "excludeOptouts": false, "excludeDuplicates": false, "spreadHours": 0, "recipients": [ { "reference": "ref-001", "text": "This is a test message with full options", "routeId": "mglobal", "originator": "Brand", "recipient": "440000001" } ], "shortenUrls": false, "name": "August Campaign" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.mobivatebulksms.com/send/batch" headers = { "Content-Type": "application/json", "Authorization": "Bearer [API KEY]" } payload = { "routeId": "mglobal", "scheduleDateTime": "2024-08-01T10:00:00+0200", "excludeOptouts": False, "excludeDuplicates": False, "spreadHours": 0, "recipients": [ { "reference": "ref-001", "text": "This is a test message with full options", "routeId": "mglobal", "originator": "Brand", "recipient": "440000001" } ], "shortenUrls": False, "name": "August Campaign", "id": "campaign-001" } response = requests.post(url, json=payload, headers=headers) ``` {% endtab %} {% endtabs %} {% hint style="warning" %} **Please note,** to schedule a date time as a parameter, the date time parameter must be set to a time in the future. {% endhint %} **Headers** | Header | Value | | ------------- | ----------------- | | Content-Type | application/json | | Authorization | Bearer \[Api-Key] | **Body**
NameTypeRequired?Description
routeIdstringYesRoute for messages.
namestringNoCampaign name, used for reporting purposes.
shortenUrlsbooleanNoDefault: false (URLs will not be shortened)
Set to true to shorten long URLs
Reduces message size and allows click tacking.
excludeOptoutsbooleanNoDefault: true (Optouts are excluded)
Set to false to turn off Optout filtering.
excludeDuplicatesbooleanNoDefault: true (Duplicates are excluded)
Set to false if you wish to send multiple messages to the same recipient(s).
scheduleDateTimedatetimeNoDefault: null (Campaign is sent immediately)
Specify a date/time to schedule delivery at a later date
Example: 2024-01-26T15:30:00+0530
spreadHoursintegerNoDefault: 0 (Spread the campaign over X hours) Specify a number of hours to spread the campaign over.
recipientslistYesList of recipients to send the batch of SMS messages to. See arguments below.
#### Arguments Recipient arguments are largely the same as when sending a single SMS message, [see here](/archived-docs/send-single-sms-message).
NameTypeRequired?Description
originatorstringYesOriginator/SenderID for SMS messages (MaxLength - AlphaNumeric: 11, numeric: 15).
recipientstringYesRecipient of SMS Message (Numeric only, MSISDN format inc international prefix).
textstringYesMessage text.
routeIDstringNoSpecified message route.
referencestringNoYour reference, will be provided as part of the delivery receipt for correlation.
**Response** {% tabs %} {% tab title="200" %} ```json { "id": "4dbe11c6bda241e394889f2f3cc66cf8", "name": "August Campaign", "routeId": "mglobal", "shortenUrls": false, "spreadHours": 0, "excludeOptouts": false, "excludeDuplicates": false, "scheduleDateTime": "2024-08-01T08:00:00+0000", "recipients": [ { "originator": "Brand", "recipient": "440000001", "text": "This is a test message with full options", "reference": "ref-001", "routeId": "mglobal" } ] } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} # Understanding Batch SMS Response Codes This document goes over understanding SMS responses using our API. ### Responses We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success.\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted).\ **5xx** errors indicate an error with ours servers (these are rare). ### Sample Success Response Upon a successful send request, our server will respond with a 200 (success) HTTP response code, and respond with campaign json. ```json { "id":"fd9157b74bd3475d8716a69683066f0f", "name":null, "routeId":"mglobal", "shortenUrls":false, "spreadHours":0, "excludeOptouts":true, "excludeDuplicates":false, "scheduleDateTime":null, "recipients":[ { "originator":"Brand", "recipient":"440000001", "text":"Test Message", "reference":"ref-001", "routeId":null } ] } ``` ### Sample Error Response ```json { "code":401, "message":"Unauthorized" } ``` ### Response Codes {% hint style="info" %} To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes) {% endhint %} # Search Message logs This document will go over how to search your message logs. ### `GET` `/message` Search message logs will allow you to search for any messages between two set dates. {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/message?startDate=2023-01-01&endDate=2023-01-02&pageSize=100" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } params = { 'startDate': '2023-01-01', 'endDate': '2023-01-02', 'pageSize': '100', } response = requests.get('https://api.mobivatebulksms.com/message', params=params, headers=headers) ``` {% endtab %} {% endtabs %} Retrieve 100 Messages between 2023-01-01 00:00:00 (UTC) and 2023-01-02 00:00:00 (UTC): {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/message?startDate=2023-01-01&endDate=2023-01-02&pageSize=100" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } params = { 'startDate': '2023-01-01', 'endDate': '2023-01-02', 'pageSize': '100', } response = requests.get('https://api.mobivatebulksms.com/message', params=params, headers=headers) ``` {% endtab %} {% endtabs %} Retrieve Messages between 2023-01-01 12:00:00 (AEST) and 2023-01-02 12:00:00 (AEST): {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/message?startDate=2023-01-01T12:00:00%2B1200&endDate=2023-01-02T12:00:00%2B1200" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } response = requests.get( 'https://api.mobivatebulksms.com/message?startDate=2023-01-01T12:00:00%2B1200&endDate=2023-01-02T12:00:00%2B1200', headers=headers, ) ``` {% endtab %} {% endtabs %} Retrieve Incoming Messages between 2023-01-01 and 2023-01-02: {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/message?startDate=2023-01-01&endDate=2023-01-02&direction=MO" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } params = { 'startDate': '2023-01-01', 'endDate': '2023-01-02', 'direction': 'MO', } response = requests.get('https://api.mobivatebulksms.com/message', params=params, headers=headers) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer [API Key]` | **Body**
NameTypeRequired?Description
startDatestringYes

Start Date Format(s):

  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SS+TZ

Examples:

  • 2023-01-01
  • 2023-01-01T00:00:00+0000
  • 2023-01-01T00:09:00+0900.
endDatestringYes

End Date.

Examples: See startDate.

pageintegerNoPage number.
Default: 1.
pageSizeintegerNoNumber of message records to return.
Default: 10
Max: 1000.
directionstringNoBy default we'll retrieve both Mobile Originated (MO / Incoming) and Mobile Terminated (MT / Outgoing) messages.
Optional Values: MO or MT.
**Response** Upon a successful send request, our server will respond with a 200 (success) HTTP response code, and respond with an array of messages. {% tabs %} {% tab title="200" %} ```json [ { "id":"9A0C23DD0A000A9D2FBD4671D780AFDA", "created":"2023-07-01T01:10:34+0000", "modified":"2023-07-01T01:10:39+0000", "originator":"Sender ID", "recipient":"4400011223", "body":"Test Message 1", "status":"DELIVERED", "direction":"MT", "inReplyTo":null, "routeId":"mglobal", "parts":1, "cost":0.01, "currency":"GBP", "senderReference":"ref-001", "campaignId":null }, { "id":"9A70B34A0A000A9D2FBD46712E56AB02", "created":"2023-07-01T03:00:24+0000", "modified":"2023-07-01T03:00:29+0000", "originator":"Brand", "recipient":"4400011223", "body":"Test Message 2", "status":"DELIVERED", "direction":"MT", "inReplyTo":null, "routeId":"FFBB2AA70A931B3100A1223E5804510B", "parts":1, "cost":0.02, "currency":"GBP", "senderReference":null, "campaignId":"9A70B2FE0A000A9D2FBD4671B0E64F3D" } ] ``` {% endtab %} {% tab title="200 (No messages)" %} ```json [ ] ``` {% endtab %} {% tab title="400" %} ```json { "code":400, "message":"startDate: Invalid format: \"2023-01-011\" is malformed at \"1\"" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Search for Single Message log This document will go over how to search your message logs for a specific message. ### `GET` `/message/:id` Search for a Single message log using an id. {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/message/9A0C23DD0A000A9D2FBD4671D780AFDA" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } response = requests.get('https://api.mobivatebulksms.com/message/9A0C23DD0A000A9D2FBD4671D780AFDA', headers=headers) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer [API Key]` | **Body**
NameTypeRequired?Description
idstringNoThe unique message id.
**Response** {% tabs %} {% tab title="200" %} ```json { "id":"9A0C23DD0A000A9D2FBD4671D780AFDA", "created":"2023-07-01T01:10:34+0000", "modified":"2023-07-01T01:10:39+0000", "originator":"Sender ID", "recipient":"4400011223", "body":"Test Message 1", "status":"DELIVERED", "direction":"MT", "inReplyTo":null, "routeId":"mglobal", "parts":1, "cost":0.01, "currency":"GBP", "senderReference":"ref-001", "campaignId":null } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% tab title="404" %} ```json { "code":404, "message":"Not Found" } ``` {% endtab %} {% endtabs %} We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # List OptOuts This document will go over how to list all of your OptOut requests. ### `GET` `/addressbook/optout` List all of your OptOuts between two set dates. {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/addressbook/optout?startDate=2023-01-01&endDate=2023-01-02" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } params = { 'startDate': '2023-01-01', 'endDate': '2023-01-02', } response = requests.get('https://api.mobivatebulksms.com/addressbook/optout', params=params, headers=headers) ``` {% endtab %} {% endtabs %} Retrieve 100 Optouts between 2023-01-01 00:00:00 (UTC) and 2023-01-02 00:00:00 (UTC). {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/addressbook/optout?startDate=2023-01-01&endDate=2023-01-02&pageSize=100" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } params = { 'startDate': '2023-01-01', 'endDate': '2023-01-02', 'pageSize': '100', } response = requests.get('https://api.mobivatebulksms.com/addressbook/optout', params=params, headers=headers) ``` {% endtab %} {% endtabs %} Retrieve Opt-Outs between 2023-01-01 12:00:00 (AEST) and 2023-01-02 12:00:00 (AEST). {% tabs %} {% tab title="Curl" %} ```hsts curl -X GET \ "https://api.mobivatebulksms.com/addressbook/optout?startDate=2023-01-01T12:00:00%2B1200&endDate=2023-01-02T12:00:00%2B1200" \ -H 'Authorization: Bearer [API Key]' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Authorization': 'Bearer [API Key]', } response = requests.get( 'https://api.mobivatebulksms.com/addressbook/optout?startDate=2023-01-01T12:00:00%2B1200&endDate=2023-01-02T12:00:00%2B1200', headers=headers, ) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer [Api Key]` | **Body**
NameTypeRequired?Description
startDatestringYes

Start Date Format(s):

  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SS+TZ

Examples:

  • 2023-01-01
  • 2023-01-01T00:00:00+0000
  • 2023-01-01T00:09:00+0900.
endDatestringYes

End Date.

Examples: See startDate.

pageintegerNoPage number.
Default: 1.
pageSizeintegerNoNumber of message records to return.
Default: 10
Max: 1000.
**Response** {% tabs %} {% tab title="200" %} ```json [ { "id":1354505990, "mobile":"4400111222", "note":"MO", "created":1672704203000 } ] ``` {% endtab %} {% tab title="400" %} ```json { "code":400, "message":"startDate: Invalid format: \"2023-01-011\" is malformed at \"1\"" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Add an OptOut This document will go over how to add an OptOut using our API. ### `POST` `addressbook/optout` Create an Opt-Out in our system. {% tabs %} {% tab title="Curl" %} ```hsts curl -X POST \ "https://api.mobivatebulksms.com/addressbook/optout" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "mobile": "440011122233" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'mobile': '440011122233', } response = requests.post('https://api.mobivatebulksms.com/addressbook/optout', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "mobile": "440011122233" }' #response = requests.post('https://api.mobivatebulksms.com/addressbook/optout', headers=headers, data=data) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer [API Key]` | **Body**
NameTypeRequired?Description
mobilestringYesMobile number to add to Optout list.
**Response** {% tabs %} {% tab title="200" %} ```json { "mobile":"440011122233", "note":"API", "created":1690783496000 } ``` {% endtab %} {% tab title="400" %} ```json { "code":400, "message":"Invalid mobile number" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Delete an OptOut This document will go over how to Delete an OptOut using our API. ### `DELETE` `/addressbook/optout` Delete an OptOut from our system. {% tabs %} {% tab title="Curl" %} ```hsts curl -X DELETE \ "https://api.mobivatebulksms.com/optout" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [API Key]' \ -d '{ "mobile": "440011122233" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer [API Key]', } json_data = { 'mobile': '440011122233', } response = requests.delete('https://api.mobivatebulksms.com/optout', headers=headers, json=json_data) # Note: json_data will not be serialized by requests # exactly as it was in the original request. #data = '{ "mobile": "440011122233" }' #response = requests.delete('https://api.mobivatebulksms.com/optout', headers=headers, data=data) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer [API Key]` | **Body**
NameTypeRequired?Description
mobilestringYesMobile number to add to Optout list.
**Response** {% tabs %} {% tab title="200" %} ```json { "mobile":"440011122233", "note":"API", "created":1690783496000 } ``` {% endtab %} {% tab title="400" %} ```json { "code":400, "message":"Invalid mobile number" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Unauthorized" } ``` {% endtab %} {% endtabs %} We use conventional HTTP response codes to indicate the success or failure of an API request. In general: **2xx** indicate success\ **4xx** indicate an error that failed given the information provided (e.g., a required parameter was omitted)\ **5xx** errors indicate an error with ours servers (these are rare). To see a full list of our **Response codes**, please [click here](/overview/introduction/understanding-response-codes). # Sending simple Notification messages Learn how to send simple messages using our API. This guide will go over how to send simple notification messages using our API, perfect for PIN codes or OTP (One time passwords). For this, Mobivate recommends you use our Simple API. ```http HTTP GET/POST: https://app.mobivatebulksms.com/gateway/api/simple/MT? USER_NAME=user@domain.com&PASSWORD=xxxxxxxxx&ORIGINATOR=Test&RECIPIENT=447930000000&ROUTE=mglobal&MESSAGE_TEXT=Your+PIN+is+654321 ``` **Required Parameters:** | Parameter | Description | | ------------- | ------------------------------------------------------------------------------------ | | ROUTE | Mobivate recommends using "mglobal", but other Route IDs are available upon request. | | ORIGINATOR | 11 alpha-numeric sender name or 15 digit number. | | RECIPIENT | International formatted mobile/cell number. | | MESSAGE\_TEXT | Text message (160 characters, 70 if containing Unicode (2 bytes) characters). | | USERNAME | Your username. | | PASSWORD | Your password. | {% hint style="warning" %} Please don't forget to [URL Encode](https://www.w3schools.com/tags/ref_urlencode.ASP) parameters if using the HTTP GET method. URL Encoding is **NOT** required when using HTTP POST. {% endhint %} # Sending SMS from 3rd Party Providers Learn how to send SMS in a JSON format using our API. If your service provider is already integrated with Mobivate SMS, you should be able to configure your **API Key** on their platform and this should enable you to send SMS directly from the 3rd Party software. {% hint style="info" %} The **API Key**, you can find on [our portal](https://hub.mobivate.com/) under the **User Profile** section. {% endhint %} If your service provider is not already integrated, you can ask them to do so. It should only take them few minutes to complete the integration using this simple API: ### **Request URL** ```http https://api.mobivatebulksms.com:443/send/single?api_key={API_Key which you provide to them} ``` ### **Content Type** ```json application/json ``` ### **Post Data (raw)** ```json { "originator" : "TEST", "recipient" : "447930000000", "body" : "Hello World", "routeId" : "mglobal" } ``` ### **Parameters** | Parameter | Required? | Description | | ---------- | --------- | -------------------------------------------------------------------------------------- | | routeId | Yes | Mobivate recommends using "`mglobal`", but other Route IDs are available upon request. | | originator | Yes | 11 alpha-numeric sender name or 15 digit number. | | recipient | Yes | international formatted mobile/cell number. | | body | Yes | Text message (160 characters, 70 if containing Unicode (2 bytes) characters). | | campaignId | No | Campaign ID. Requires an existing Campaign. | | reference | No | Your internal reference. | # Sending Campaigns Learn how to send campaigns using our JSON API. If your service provider is already integrated with Mobivate SMS, you should be able to configure your **API Key** on their platform and this should enable you to send SMS directly from the 3rd Party software. {% hint style="info" %} The **API Key**, you can find on [our portal](https://hub.mobivate.com/) under the **User Profile** section. {% endhint %} If your service provider is not already integrated, you can ask them to do so. It should only take them few minutes to complete the integration using this simple API: ### **Request URL** ```http https://api.mobivatebulksms.com:443/send/campaign?api_key={API_Key which you provide to them} ``` ### **Content Type** ```json application/json ``` ### **Post Data (raw)** ```json { "scheduleDateTime" : "2022-04-23T12:00:00.996+0200", "routeId" : "mglobal", "excludeOptouts" : true, "excludeDuplicates" : false, "spreadHours" : 3, "recipients" : [ { "reference" : "Testing", "text" : "Hello World", "routeId" : "mglobal", "originator" : "TEST", "recipient" : "447930000000", } ], "shortenUrls" : false, "name" : "Test Name", } ``` ### **Campaign Parameters:** | Parameter | Required? | Description | | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | scheduleDateTime | No | .A date/time parameter to be used if you want to schedule your request to be sent in the future. Must contain hours, minutes and seconds. Timezone follows the ISO 8601 time formatting. | | routeId | Yes | Mobivate recommends using "mglobal", but other Route IDs are available. The route ID, can be specified in each recipient. | | excludeOptouts | No | A true or false field indicating if you want to exclude OptOuts. | | excludeDuplicates | No | A true or false field indicating if you want to exclude duplicate records. | | spreadHours | No | An integer indicating how many hours you want to spread the messages across. | | recipients | Yes | A list of Recipient Objects. | | shortenUrls | No | A true/false field can be used to shorten URL's in the body text. Additional costs apply. | | name | No | The campaign name. | ### **Recipient Object Parameters:** | Parameter | Required? | Description | | ---------- | --------- | ----------------------------------------------------------------------- | | reference | No | Individual message reference, if declared must be unique per recipient. | | text | Yes | The text body of the message being sent. | | routeId | No | Allows to override the routeID set on the campaign per recipient. | | originator | Yes | 11 alpha-numeric sender name or 15 digit number. | | recipient | Yes | Recipient number, MSISDN / International number E.G. 447930000000. | # Integrating Mobivate framework into your own application Learn how to Integrate Mobivate's framework. Looking to integrate our framework into your very own application? Great! We offer ready-made libraries on our [GitHub page](https://github.com/mobivate). {% embed url="" %} Download the latest files for your application {% endembed %} If you require full API documentation, please download the [PDF document](https://www.dropbox.com/s/a4je9gebc67q67z/blender-api-1.5.0-clean.pdf?dl=1). {% hint style="info" %} Note: For the XML API, all requests should go to {% endhint %} # Automate SMS messages using events through Zapier Learn how to send automated SMS messages using our integration with Zapier. Mobivate is integrated with more than **1500** apps via Zapier: #### MondayCLIAPI@2.1.1 logoMobivateBulkSMSCLIAPI@1.0.3 logo**Send texts via Mobivate BulkSMS for new items on boards in monday.com** [Click here to find out more](https://zapier.com/security/iframe-blocked?next=%2Fsign-up%3Fnext%3D%252Fwebintent%252Fcreate-zap%253Fentry-point-location%253Dpartner_embed%26attempt_id%3D2b7c9b01-0df1-44c0-98b5-1632dc22cddd%26provider%3Dmobivate-bulksms%26provider%3Dmobivate-bulksms%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%26template%3D78220%26template%3D78220%26entry-point-location%3Dpartner_embed%26referrer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%26referrer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_source%3Dpartner%26utm_source%3Dpartner%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element\&blocked_uri=https%3A%2F%2Fapp.gitbook.com%2Fo%2F2gNvSOgxbpoMWbES48Yx%2Fs%2FlQ6wwnR18L0Tgg5BKK13%2F~%2Fchanges%2F15%2Fintegrations%2Fautomate-sms-messages-using-events-through-zapier) #### GoogleSheetsV2API logoMobivateBulkSMSCLIAPI@1.0.3 logo**Send texts via Mobivate BulkSMS for new Google Sheets spreadsheet rows** [Click here to find out more](https://zapier.com/sign-up?next=%2Fwebintent%2Fcreate-zap%3Ftemplate%3D155386\&attempt_id=21a2dc1c-53c1-4979-9e99-6d6373c6c24f\&provider=mobivate-bulksms\&provider=mobivate-bulksms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner%26utm_medium%3Dembed%26utm_campaign%3Dzap_templates_element%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms\&template=155386\&entry-point-location=partner_embed\&entry-point-location=partner_embed\&referrer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner%26utm_medium%3Dembed%26utm_campaign%3Dzap_templates_element%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms\&referrer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner\&utm_medium=embed\&utm_medium=embed\&utm_medium=embed\&utm_medium=embed\&utm_source=partner\&utm_source=partner\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element) #### GoogleCalendarAPI logoMobivateBulkSMSCLIAPI@1.0.3 logoGet reminders with Mobivate BulkSMS for your events starts in Google Calendar [Click here to find out more](https://zapier.com/security/iframe-blocked?next=%2Fsign-up%3Fnext%3D%252Fwebintent%252Fcreate-zap%253Ftemplate%253D205854%26attempt_id%3De38eefd3-3e47-48b7-84ae-b4439ea0aa9b%26provider%3Dmobivate-bulksms%26provider%3Dmobivate-bulksms%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%2526utm_medium%253Dembed%2526utm_campaign%253Dzap_templates_element%2526referer%253Dhttps%25253A%25252F%25252Fwww.mobivate.com%25252Fdevelopers%25252Fbulk-sms%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%26template%3D205854%26entry-point-location%3Dpartner_embed%26entry-point-location%3Dpartner_embed%26referrer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%2526utm_medium%253Dembed%2526utm_campaign%253Dzap_templates_element%2526referer%253Dhttps%25253A%25252F%25252Fwww.mobivate.com%25252Fdevelopers%25252Fbulk-sms%26referrer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms%253Futm_source%253Dpartner%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_medium%3Dembed%26utm_source%3Dpartner%26utm_source%3Dpartner%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element%26utm_campaign%3Dzap_templates_element\&blocked_uri=https%3A%2F%2Fapp.gitbook.com%2Fo%2F2gNvSOgxbpoMWbES48Yx%2Fs%2FlQ6wwnR18L0Tgg5BKK13%2F~%2Fchanges%2F14%2Fintegrations%2Fautomate-sms-messages-using-events-through-zapier) #### ZendeskV2API logoMobivateBulkSMSCLIAPI@1.0.3 logo**Send SMS messages in Mobivate BulkSMS to new Zendesk users** [Click here to find out more](https://zapier.com/sign-up?next=%2Fwebintent%2Fcreate-zap%3Ftemplate%3D205859\&attempt_id=30f770af-fb94-4243-a1a5-ffe85f8d5184\&provider=mobivate-bulksms\&provider=mobivate-bulksms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner%26utm_medium%3Dembed%26utm_campaign%3Dzap_templates_element%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms\&template=205859\&entry-point-location=partner_embed\&entry-point-location=partner_embed\&referrer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner%26utm_medium%3Dembed%26utm_campaign%3Dzap_templates_element%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms\&referrer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner\&utm_medium=embed\&utm_medium=embed\&utm_medium=embed\&utm_medium=embed\&utm_source=partner\&utm_source=partner\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element) #### MobivateBulkSMSCLIAPI@1.0.3 logoZendeskV2API logo**Create Zendesk tickets from new Mobivate BulkSMS messages** [Click here to find out more](https://zapier.com/sign-up?next=%2Fwebintent%2Fcreate-zap%3Ftemplate%3D205864\&attempt_id=afd52755-aa9b-44a2-99a8-f9d0416c0795\&provider=mobivate-bulksms\&provider=mobivate-bulksms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner%26utm_medium%3Dembed%26utm_campaign%3Dzap_templates_element%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms\&referer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms\&template=205864\&entry-point-location=partner_embed\&entry-point-location=partner_embed\&referrer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner%26utm_medium%3Dembed%26utm_campaign%3Dzap_templates_element%26referer%3Dhttps%253A%252F%252Fwww.mobivate.com%252Fdevelopers%252Fbulk-sms\&referrer=https%3A%2F%2Fwww.mobivate.com%2Fdevelopers%2Fbulk-sms%3Futm_source%3Dpartner\&utm_medium=embed\&utm_medium=embed\&utm_medium=embed\&utm_medium=embed\&utm_source=partner\&utm_source=partner\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element\&utm_campaign=zap_templates_element) ### Not seeing what you're looking for? [Create from scratch](https://zapier.com/webintent/create-zap/?utm_source=partner\&utm_medium=embed\&utm_campaign=zap_templates_element) or [learn more](https://zapier.com/how-it-works/?utm_source=partner\&utm_medium=embed\&utm_campaign=zap_templates_element). # Asynchronous Number Verification Learn how to perform Asynchronous number verification using our API To verify if the number is valid (active on any network), you can request a Home Location Register (HLR) lookup. Please be aware that this is Asychronous and should be handled one at a time. ```http HTTP GET: https://app.mobivatebulksms.com/gateway/api/simple/MT?USER_NAME=....&PASSWORD=....&ORIGINATOR=HLR&RECIPIENT=....&ROUTE=mhlrglobal ``` On success, we will return **XML**: ```xml truetrue0HLRfalsemhlrglobalfalsetrue.......MSISDN ``` # Synchronous Number Verification Learn how to use our Synchronous number verification system To verify if the number is valid (active on any network), you can request a Home Location Register (HLR) lookup. ```http HTTP GET: https://hlr.mobivatebulksms.com/?lookup={msisdn,msisdn,...}&username={your username}&password={your password} ``` On success, we will return **JSON**: ```json { results: [ { to: "4474*******", mccMnc: "23430", imsi: "23430", originalNetwork: { networkName: "T-Mobile UK (Everything Everywhere Limited)", networkPrefix: "74326", countryName: "United Kingdom", countryPrefix: "44" }, ported: false, status: { groupId: 3, groupName: "DELIVERED", id: 5, name: "DELIVERED_TO_HANDSET", description: "Message delivered to handset" }, error: { groupId: 0, groupName: "OK", id: 0, name: "NO_ERROR", description: "No Error", permanent: false } }, { ... }, ] } ``` # Adding / Removing Contacts Learn how to add/remove contacts with our API ### `GET` `/api/contacts` Add or delete contacts from our applications using our proxy API. {% tabs %} {% tab title="Curl" %} ```hsts curl -XGET 'https://tasks-wave.mobivate.com/api/contacts/create?username=username&password=password&msisdn=447000000001&applications=optouts:call' ``` {% endtab %} {% tab title="Python" %} ```python import requests response = requests.get( 'https://tasks-wave.mobivate.com/api/contacts/create?username=username&password=password&msisdn=447000000001&applications=optouts:call', ) ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Curl" %} ```http curl -XGET 'https://tasks-wave.mobivate.com/api/contacts/delete?username=username&password=password&msisdn=447000000001&applications=optouts:call' ``` {% endtab %} {% tab title="Python" %} ```python import requests response = requests.get( 'https://tasks-wave.mobivate.com/api/contacts/delete?username=username&password=password&msisdn=447000000001&applications=optouts:call', ) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `No Auth` | **Body** | Parameter | Required | Description | | ------------ | -------- | --------------------------------------------------------------------------------------------- | | username | Yes | The username used to login to Mobivate. | | password | Yes | The password used to login to Mobivate. | | msidn | Yes | Phone number in international format. | | applications | Yes | Comma separated list of applications to subscribe to / remove from (see below). | | name | No | The contacts name to use. | | reference | No | Optional custom reference for the contact, used as callcentre reference id or custom 1 field. | {% hint style="info" %} Please note. Supplied reference is for your identification only. {% endhint %} **Response** {% tabs %} {% tab title="200" %} ```json { "status": "ok", "optouts:robocall": "ok" } ``` {% endtab %} {% tab title="401" %} ```json { "code":401, "message":"Not Authenticated" } ``` {% endtab %} {% endtabs %} ### **Applications** Applications are denoted as a comma `","` separated list, with colon `":"` as the separator between the app name and identification token of the contact group/recurring campaign. | Application Name | Description | | ----------------------- | ---------------------------- | | appointments | The appointment booking app. | | recurring: `CampaignId` | The periodic reminder app. | | contacts: `ListId` | The main contacts app. | | callcentre: `SetupId` | The Callcentre app. | | optouts: `sms / call` | Generic optouts. | ### **Finding the Identification Tokens** **Recurring** The `CampaignId` can be obtained as the last numeric parameter of the url while editing the campaign details. **Contacts Group** The `ContactGroupId` is shown on the group details at the bottom of the right column. **CallCentre** The `SetupId` is shown on the setup details at the bottom of the right column. **OptOuts** The identification is either `sms` for sms optouts or `calls` for robocall optouts. To find out more about our applications, [click here](https://www.mobivate.com/bulk-sms/system-features). # Creating New Contact Group Learn how to create a new contact group with our API. ### `GET` `/api/contacts/create_contactgroup/` Create a new contact group using our proxy API. {% tabs %} {% tab title="Curl" %} ```http curl -XGET 'https://tasks-wave.mobivate.com/api/contacts/create_contactgroup/?username=username&password=password&group_name=MyGroup ``` {% endtab %} {% tab title="Python" %} ```python import requests response = requests.get( 'https://tasks-wave.mobivate.com/api/contacts/create_contactgroup/?username=username&password=password&group_name=MyGroup', ) ``` {% endtab %} {% endtabs %} **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `No Auth` | **Body** | Parameter | Required | Description | | ----------- | -------- | --------------------------------------- | | username | Yes | The username used to login to Mobivate. | | password | Yes | The password used to login to Mobivate. | | group\_name | No | Your contact group name. | **Response** {% tabs %} {% tab title="200" %} ```json { "status": "ok", "group_id": "group_id" } ``` {% endtab %} {% tab title="403" %} ```json { "message":"Not Authenticated" } ``` {% endtab %} {% endtabs %}