+971-4-440-2600 +971-4-440-2600

REST

Integrate SMS Sending Capabilities

Looking for information regarding our v1 documentation? Contact us now for further details.

Introduction

The REST API allows programmatic access to SMSGlobal features in MXT. To use the REST API, you will need an MXT account and an API key and secret. You can generate these inside your MXT account. The REST API can be accessed at api.smsglobal.com. Use of SSL is supported and strongly encouraged. The REST API takes full advantage of all HTTP headers. Each part of a request and response is meaningful, including the request method (GET/POST, etc.), the individual headers (Location, Content-Type, Accept, etc.), and the response status code (200, 400, 404, etc.). Use of this API assumes a working knowledge of these HTTP components, and general use of RESTful web APIs.

Authentication Scroll to Top ▲

The REST API uses an authentication scheme based on this OAuth 2 specification . All requests to resources (excluding the schema pages) must be accompanied by a correct Authorization header as per this specification. The header looks like this:

 Authorization: MAC id="your API key", ts="1325376000", nonce="random-string", mac="base64-encoded-hash"

Authorization header fields Scroll to Top ▲

The value of the header is made up of the following components.

FieldMeaning

id

Your API key, issued to you by SMSGlobal. Information on managing API keys can be found here .

ts

The Unix timestamp of the time you made the request. We allow a slight buffer on this in case of any time sync issues.

nonce

A randomly generated string of your choice. Ensure it is unique to each request, and no more than 32 characters long.

To prevent replay attacks, a single nonce can only be used once.

mac

This is the base 64 encoded hash of the request.

Calculating the mac hash

The hash is a SHA-256 digest of a concatenation of a series of strings related to the request. The string is:

Timestamp
 Nonce
 HTTP request method
 HTTP request URI
 HTTP host
 HTTP port
 Optional extra data

Each part of the string is separated by a line feed character (\n or 0x0A; not \r or \r\n). The entire string also ends with a line feed character. Here’s an example for a POST request to the sms resource via HTTPS. The \n characters are shown for clarity.

 1325376000\n
 random-string\n
 POST\n
 /v2/sms/\n
 api.smsglobal.com\n
 443\n
 \n

Note that the optional extra data line is blank. Our API does not currently use this field, but it must be included in the hash as an empty string as per the OAuth 2 specification. Once this string has been constructed, you must then hash it using the HMAC method, with your API secret (issued with your API key) used as the hash key. SMSGlobal uses the SHA-256 algorithm for hashing. It is recommended that you use a pre-existing library to calculate the hash, as it is quite calculated. Ensure the hash is output in binary, and not in hexadecimal. Once the hash is calculated, base 64 encode it and include it in the HTTP header. For this example, the hashed string is:

 EJQ15pg5cEYsotgQaGyCHRxnPvmAemamOh6w7YRDif4

Things to check include checking to ensure the REST API keys are correct as well as the time they are authenticating with.

The computer must have accurate time as the authentication MAC is build using the time, so authentication will fail if the client computer time is different to our server time.

Response Codes Scroll to Top ▲

The following response codes apply to all requests. Check each request type in the list below for more response codes specific to that request.

Status CodeMeaningScenario

200

OK

The request was processed successfully

400

Bad Request

Your request contained invalid or missing data

401

Unauthorized

Authentication failed or the Authenticate header was not provided

404

Not Found

The URI does not match any of the recognised resources, or, if you are asking for a specific resource with an ID, that resource does not exist

405

Method Not Allowed

The HTTP request method you are trying to use is not allowed. Make an OPTIONS request to see the allowed methods

406

Not Acceptable

The Accept content type you are asking for is not supported by the REST API

415

Unsupported Media Type

The Content-Type header is not supported by the REST API

Response and Request Data Formats Scroll to Top ▲

You can specify the formats you want to use for request and response data.

Supported Request Formats Scroll to Top ▲

Use the Content-Type header to specify the format your data is in.

  • JSON: application/json
  • XML: application/xml

Supported Response Formats Scroll to Top ▲

Use the Accept header to specify the output desired format.

If you can’t set that header, use the format parameter in the query string. The format parameter takes precedence over the Accept header.

  • JSON: application/json
  • XML: application/xml

HTTP Post Backs Scroll to Top ▲

You can get HTTP post-backs for delivery receipts, message status updates and incoming messages.

Post-backs are HTTP GET requests by default and parameters passed in the query string. You can set the post-back format in the following formats.

Delivery Receipts Scroll to Top ▲

Click here to see more on Delivery Receipts

Message Status Updates Scroll to Top ▲

SMSGlobal can notify you of change in message delivery status to allow you to monitor the status of messages sent.

To use notifyURL, delivery receipts will need to be enabled in your MXT settings first.

Please find below the list of parameters that are sent.

FieldMeaning

id

Message part identifier

status

Current status of the sms message

update_time

The date in UTC when the message status was updated

outgoing_id

Outgoing message identifier

Examples
 https://example.url?id=6419785166510955&outgoing_id=5346907663&status=Delivered&update_time=2020-09-16T16%3A32%3A17%2B10%3A00 
 id=6419785166510955&outgoing_id=5346907663&status=Delivered&update_time=2020-09-16T16%3A32%3A17%2B10%3A00 
 {
 "id":"6968154134564265",
 "outgoing_id":"5347047793",
 "status":"Delivered",
 "update_time":"2020-09-16T16:50:33+10:00"
 } 
 <?xml version="1.0" encoding="UTF-8"?>
 <delivery_receipt>
 <id>6929949692100437</id>
 <outgoing_id>5347049893</outgoing_id>
 <status>Delivered</status>
 <updated_time>2020-09-16T16:53:09+10:00</updated_time>
 </delivery_receipt>

Incoming Messages Scroll to Top ▲

If you would like to receive notification of your Incoming SMS to be pushed to your server, please ensure you specify a URL in your outgoing message request or default URL in your account settings.

In order for our system to know that your URL has received the delivery notice, at the end of your script you must echo out “OK”.

Please find below the list of parameters that are sent.

FieldMeaning

to

Mobile Terminated Number, where the message was sent to

from

Mobile Originated Number, where the message was sent from

msg

Contents of the message

date

Date the message was received by SMSGlobal.

msgid

Message identifier

Examples
 http://www.example.com/?from=61433111222&to=61499057767&msg=response+&date=2020-09-16+16%3A29%3A50&msgid=471047771 
from=61433111222&to=61499057767&msg=response+&date=2020-09-16+16%3A29%3A50&msgid=471047771
{
 "from":"61433111222",
 "to":61499057767,
 "msg":"response ",
 "date":"2020-09-16 16:51:59",
 "msgid":471051471
 }
<?xml version="1.0" ?>
 <incoming>
 <from>61433111222</from>
 <to>61499057767</to>
 <msg>response</msg>
 <date>2020-09-16 16:53:19</date>
 <msgid>471051701</msgid>
 </incoming>

API Endpoints Scroll to Top ▲

  • auto-topup
    /v2/auto-topup
    • GET /v2/auto-topup stable since v2

      Documentation

      Get the auto top-up information associated to the authenticated account.

      Return

      ParameterTypeVersionsDescription
      disabledboolean>=v2Whether auto top-up is disabled for the authenticated user.
      balanceThresholdinteger>=v2The auto top-up low balance threshold.
      balanceAmountinteger>=v2The auto top-up amount.
      cardobject (CreditCards)>=v2The credit card to be charged the auto top-up amount.
      card[number]string>=v2Masked credit card number
      card[type]string>=v2Credit card type
      periodicFrequencyinteger>=v2The auto top up periodic frequency.
      periodicStartDateDateTime>=v2The auto top up start date
      periodicEndDateDateTime>=v2The auto top up end date
      periodicAmountinteger>=v2The periodic top up amount

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
  • contact group
    /v2/contact/{id}
    • DELETE /v2/contact/{id} stable since v2

      Documentation

      Delete a contact

      Requirements

      NameRequirementTypeDescription
      id\d+integerThe contact identifier.

      Status Codes

      Status CodeDescription
      204
      • Returned when the contact is deleted successfully
      403
      • Returned when the user is not authorized to perform action
      404
      • Returned when contact is not found
      405
      • Method is not allowed
    • GET /v2/contact/{id} stable since v2

      Documentation

      Get the contact as identified by the given id.

      Requirements

      NameRequirementTypeDescription
      id\d+integerThe contact identifier.

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2
      groupIdstring>=v2
      givenNamestring>=v2Contact given name.
      familyNamestring>=v2Contact surname.
      displayNamestring>=v2Contact display name.
      msisdnstring>=v2Contact mobile number.
      emailAddressstring>=v2Contact email address.
      Status CodeDescription
      200
      • Returned when the contact is deleted successfully
      403
      • Returned when the user is not authorized to perform action
      404
      • Returned when contact is not found
      405
      • Method is not allowed
    • PUT /v2/contact/{id} stable since v2

      Documentation

      Update the contact as identified by the given id. You can only update the default fields associated with each contact.

      Requirements

      NameRequirementTypeDescription
      id\d+integerThe contact identifier.

      Parameters

      ParameterTypeRequired?FormatDescription
      givenNamestringtrueGiven name.
      familyNamestringtrueFamily name.
      displayNamestringtrueDisplay name.
      msisdnstringtrueMobile number. Maximum of 15 characters.
      emailAddressstringtrueEmail address.
      Status CodeDescription
      204
      • Returned when successfull
      403
      • Returned when the user is not authorized
      404
      • Returned when contact is not found
      405
      • Method is not allowed
    /v2/group
    • GET /v2/group stable since v2

      Documentation

      Get a list of all contact groups.

      Filters

      NameInformation
      offsetRequirement \d+
      Description Pagination offset (default 1)
      Default 1
      limitRequirement \d+
      Description Number of items to return (default 20)
      Default 20

      Return

      ParameterTypeVersionsDescription
      offsetinteger*
      limitinteger*
      totalinteger*
      groups[]array of objects (ContactGroup)>=v2A collection of contact groups
      groups[][id]integer>=v2
      groups[][name]string>=v2
      groups[][keyword]string>=v2
      groups[][isGlobal]boolean>=v2
      groups[][contactCount]integer>=v2
      groups[][defaultOrigin]string>=v2
      Status CodeDescription
      200
      • Returned when the contact is deleted successfully
      403
      • Returned when the user is not authorized to perform action
      405
      • Method is not allowed
    • POST /v2/group stable since v2

      Documentation

      Create a new contact group.

      Parameters

      ParameterTypeRequired?FormatDescription
      namestringtrueGroup name. Max length of 100 characters.
      keywordstringfalseEmail to SMS keyword.
      defaultOriginstringfalseThe default SMS origin for this group. 4-11 characters for alphanumeric or 4-15 * digits for numeric. Defaults to shared pool numbers.
      isGlobalbooleanfalseIs the group globally visible to sub accounts. Defaults to false.
      Status CodeDescription
      200
      • Returned when the contact is deleted successfully
      400
      • Returned when the request is bad.
      403
      • Returned when the user is not authorized to perform action
      405
      • Method is not allowed
    /v2/group/{groupId}/contact
    • POST /v2/group/{groupId}/contact stable since v2

      Documentation

      Create a contact

      Requirements

      NameRequirementType?Description
      groupId\d+integerThe contact group identifier.

      Parameters

      ParameterTypeRequired?FormatDescription
      msisdnstringtrueGroup name. Max length of 100 characters.
      givenNamestringfalseGiven name.
      familyNamestringfalseFamily name.
      displayNamestringfalseDisplay name.
      emailAddressstringfalseEmail address.
      contacts[]array of objects (Contact)falseA collection of contacts
      contacts[][givenName]stringfalse
      contacts[][familyName]stringfalse
      contacts[][displayName]stringfalse
      contacts[][msisdn]stringfalse
      contacts[][emailAddress]stringfalse
      Status CodeDescription
      201
      • Returned when the contact is deleted successfully
      400
      • Returned when the request is bad.
      403
      • Returned when the user is not authorized to perform action
      405
      • Method is not allowed
    /v2/group/{groupId}/contacts
    • GET /v2/group/{groupId}/contacts stable since v2

      Documentation

      Get a list of all contacts in a group.

      Requirements

      NameRequirementTypeDescription
      id\d+integerThe contact group identifier.
      groupId

      Filters

      NameInformation
      offsetRequirement \d+
      Description Pagination offset (default 1)
      Default 1
      limitRequirement \d+
      Number of items to return (default 20)
      Default 20
      sortRequirement string
      Description Sort by field id or msisdn. Prefix with minus (-) for descending order.
      Default id
      Status CodeDescription
      200
      • Returned when successful
      400
      • Returned when the request is bad.
      403
      • Returned when the user is not authorized to perform action
      404
      • Returned when the group is not found
      405
      • Method is not allowed
    /v2/group/{id}
    • DELETE /v2/group/{id} stable since v2

      Documentation

      Delete a contact group

      Requirements

      NameRequirementTypeDescription
      id\d+integerThe contact group identifier.
      groupId

      Status Codes

      Status CodeDescription
      204
      • Returned when successful
      403
      • Returned when the user is not authorized to perform action
      404
      • Returned when the group is not found
      405
      • Method is not allowed
    • GET /v2/group/{id} stable since v2

      Documentation

      Get the contact group as identified by the given id.

      Requirements

      NameRequirementTypeDescription
      id\d+integerThe contact group identifier.

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2
      namestring>=v2
      keywordstring>=v2
      isGlobalboolean>=v2
      contactCountinteger>=v2
      defaultOriginstring>=v2

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      404
      • Returned when the group is not found
      405
      • Method is not allowed
    • PATCH /v2/group/{id} stable since v2

      Documentation

      Update fields of a group as identified by the given id.

      Requirements

      NameRequirementTypeDescription
      id\d+integerThe contact group identifier.

      Parameters

      ParameterTypeRequired?FormatDescription
      namestringfalseGroup name. Max length of 100 characters.
      keywordstringfalseEmail to SMS keyword.
      defaultOriginstringfalseThe default SMS origin for this group. 4-11 characters for alphanumeric or 4-15 * digits for numeric. Pass an empty string " for shared pool numbers.
      isGlobalbooleanfalseIs the group globally visible to sub accounts. Defaults to false.

      Status Codes

      Status CodeDescription
      204
      • Returned when successful
      400
      • Returned when the request is bad.
      403
      • Returned when the user is not authorized.
      405
      • Returned when the method is not allowed.
  • dedicated-number
    /v2/dedicated-number
    • GET /v2/dedicated-number stable since v2

      Documentation

      View list of dedicated numbers

      Return

      ParameterTypeVersionsDescription
      dedicatedNumbers[]array of objects (DedicatedNumber)>=v2A collection of Dedicated Number objects
      dedicatedNumbers[][id]integer>=v2Dedicated number identifier
      dedicatedNumbers[][userId]integer>=v2User identifier
      dedicatedNumbers[][msisdn]string>=v2Mobile phone number including country and area codes. 4 to 15 digits; no spaces or other formatting
      dedicatedNumbers[][type]string>=v2How to handle incoming messages. 0 = Disable this number, 1 = SMPP, 2 = HTTP Callback, 3 = Email, 4 = SMSGlobal website only. All messages still appear on the SMSGlobal website regardless of this setting
      dedicatedNumbers[][emailAddress]integer>=v2Email address to send incoming SMS to
      dedicatedNumbers[][httpCallbackUrl]integer>=v2HTTP callback URL for incoming SMS
      dedicatedNumbers[][isAutoReplyEnabled]boolean>=v2Whether auto reply messages are enabled
      dedicatedNumbers[][autoReplyMessage]string>=v2The auto reply message. Maximum of 480 characters
      dedicatedNumbers[][autoReplyOrigin]string>=v2Where the auto reply should appear to come from. Blank to use the dedicated number itself. 4-15 digits or 3-11 numbers and letters

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
  • opt-outs
    /v2/opt-outs
    • GET /v2/opt-outs beta since v2

      Documentation

      View list of opted out numbers

      Filters

      NameInformation
      phoneNumberRequirement [0-9]+
      Description Filter by phone number
      Default
      offsetRequirement \d+
      Description Pagination Offset (default 1)
      Default 1
      limitRequirement \d+
      Description Number of items to return (default 20)
      Default 20

      Return

      ParameterTypeVersionsDescription
      optouts[]array of objects (Optout)>=v2A collection of Optout number object. Optout object consist of number and status(exist, valid, and invalid) properties.
      offsetinteger*
      limitinteger*
      totalinteger*

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    • POST /v2/opt-outs beta since v2

      Documentation

      Opt out mobile numbers

      Requirements

      NameRequirementTypeDescription
      optoutsarrayarray of Opt-out mobile numbers

      Return

      ParameterTypeVersionsDescription
      optouts[]array of objects (Optout)>=v2A collection of Optout number object. Optout object consist of number and status(exist, valid, and invalid) properties.

      Status Codes

      Status CodeDescription
      204
      • Returned when numbers opted-out successfully
      400
      • Returned when request parameter is invalid
      403
      • Returned when the user is not authorized to perform action
      405
      • Method not allowed
    /v2/opt-outs/validate
    • POST /v2/opt-outs/validate beta since v2

      Documentation

      Validate mobile numbers for opt out

      Requirements

      NameRequirementTypeDescription
      optoutsarrayarray of Opt-out mobile numbers

      Return

      ParameterTypeVersionsDescription
      optouts[]array of objects (Optout)>=v2A collection of Optout number object. Optout object consist of number and status(exist, valid, and invalid) properties.

      Status Codes

      Status CodeDescription
      200
      • Returned when numbers opted-out successfully
      400
      • Returned when request parameter is invalid
      403
      • Returned when the user is not authorized to perform action
      405
      • Method not allowed
    /v2/opt-outs/{number}
    • DELETE /v2/opt-outs/{number} beta since v2

      Documentation

      Opt in a mobile number

      Requirements

      NameRequirementTypeDescription
      number\d+integerOpt in mobile number (msidn)

      Status Codes

      Status CodeDescription
      204
      • Returned when number opted-in successfully
      400
      • Returned when the user is not authorized to perform action
      403
      • Returned when number is not found
      405
      • Method not allowed
  • sharedpool
    /v2/sharedpool
    • GET /v2/sharedpool beta since v2

      Documentation

      View list of shared pools

      Return

      ParameterTypeVersionsDescription
      SharedPools[]array of objects (SharedPool)>=v2A collection of shared pool objects
      SharedPools[][id]integer>=v2Shared pool identifier
      SharedPools[][name]string>=v2
      SharedPools[][size]integer>=v2
      SharedPools[][numbers][]array of objects
      (DedicatedNumber)      		>=v2
      SharedPools[][numbers][]
      [msisdn]      		string>=v2Mobile phone number including country and area codes. 4 to 15 digits; no spaces or other formatting

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/sharedpool/{id}
    • GET /v2/sharedpool/{id} beta since v2

      Documentation

      View details of a shared pool

      Requirements

      NameRequirementTypeDescription
      id\d+integerShared pool id

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2Shared pool identifier
      namestring>=v2
      sizeinteger>=v2
      numbers[]array of objects
      (DedicatedNumber)      		>=v2
      numbers[]
      [msisdn]      		string>=v2Mobile phone number including country and area codes. 4 to 15 digits; no spaces or other formatting
      Status CodeDescription
      200
      • Returned when successful
      204
      • Returned when the sharedpool id is not valid
      403
      • Returned when the user is not authorized
      404
      • Returned when sharedpool does not exist
      405
      • Method is not allowed
  • sms
    /v2/sms
    • GET /v2/sms stable since v2

      Documentation

      View list of outgoing messages

      Filters

      NameInformation
      offsetRequirement \d+
      Description Pagination offset (default 1, maximum offset + limit = 10,000)
      Default 1
      limitRequirement \d+
      Description Number of items to return (default 20, maximum 1000)
      Default 20
      statusRequirement
      Description Filter by message status. Allowed values [delivered, sent, scheduled, noCredits, invalidNumber, undelivered]
      startDateRequirement
      Description Start date of the date range filter. Date format in account timezone
      endDateRequirement
      Description End date of the date range filter. Date format in account timezone
      destinationRequirement \d+
      Description The number message was sent to
      sourceRequirement \d+
      Description The number message was sent from
      searchRequirement \d+
      Description Search string in source, destination and message

      Return

      ParameterTypeVersionsDescription
      totalinteger>=v2Total number of sms sent message objects.
      offsetinteger>=v2Pagination Offset (default 1)
      limitinteger>=v2Number of outgoing message objects to return
      messages[]array of objects (SmsSent)>=v2A collection of outgoing message objects
      messages[][id]array of objects (SmsSent)>=v2Message part identifier
      messages[][outgoing_id]array of objects (SmsSent)>=v2Outgoing message identifier
      messages[][origin]string>=v2Where the SMS appears to come from. 4-11 characters A-Za-z0-9 if alphanumeric; 4-15 digits if numeric (if set, set sharedPool to null)
      messages[][destination]string>=v2Destination mobile number. 4-15 digits
      messages[][message]string>=v2Outgoing message
      messages[][status]string>=v2Message status
      messages[][dateTime]string>=v2The date the message was created in UTC

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    • POST /v2/sms stable since v2

      Parameters

      ParameterTypeRequired?FormatDescription
      destinationstringfalseDestination mobile number. 3-15 digits
      destinations[]array of stringsfalseA collection of destination mobile numbers. 3-15 digits
      messagestringfalseThe SMS message. If longer than 160 characters (GSM) or 70 characters (Unicode), splits into multiple SMS
      originstringfalseWhere the SMS appears to come from. 3-11 characters A-Za-z0-9 if alphanumeric; 3-15 digits if numeric (if set, set sharedPool to null)
      scheduledDateTimedatetimefalseyyyy-MM-dd HH:mm:ssThe datetime the message should be sent in UTC
      campaigndatetimefalseyyyy-MM-dd HH:mm:ssThe campaign the message is associated with (optional)
      sharedPoolstringfalseThe shared pool to use (if set, set origin to null)
      notifyUrlstringfalseUrl to post back the status of message
      incomingUrlstringfalseUrl to post back incoming messages
      expiryDateTimedatetimefalseyyyy-MM-dd HH:mm:ssThe datetime in UTC at message will expire
      messages[]array of objects (Sms)trueA collection of sms messages
      messages[][destination]stringfalseDestination mobile number. 3-15 digits
      messages[][destinations][]array of stringsfalseA collection of destination mobile numbers. 3-15 digits
      messages[][message]stringfalseThe SMS message. If longer than 160 characters (GSM) or 70 characters (Unicode), splits into multiple SMS
      messages[][origin]stringfalseWhere the SMS appears to come from. 3-11 characters A-Za-z0-9 if alphanumeric; 3-15 digits if numeric (if set, set sharedPool to null)
      messages[][scheduledDateTime]datetimefalseyyyy-MM-dd HH:mm:ssThe datetime the message should be sent in UTC
      messages[][campaign]stringfalseThe campaign the message is associated with (optional)
      messages[][sharedPool]stringfalseThe shared pool to use (if set, set origin to null)
      messages[][notifyUrl]stringfalseUrl to post back the status of message
      messages[][incomingUrl]stringfalseUrl to post back incoming messages
      messages[][expiryDateTime]datetimefalseyyyy-MM-dd HH:mm:ssThe datetime in UTC at message will expire

      Return

      ParameterTypeVersionsDescription
      messages[]array of objects (SmsSent)>=v2A collection of outgoing message objects
      messages[][id]integer>=v2Message part identifier
      messages[][outgoing_id]integer>=v2Outgoing message identifier
      messages[][origin]string>=v2Where the SMS appears to come from. 4-11 characters A-Za-z0-9 if alphanumeric; 4-15 digits if numeric (if set, set sharedPool to null)
      messages[][destination]string>=v2Destination mobile number. 4-15 digits
      messages[][message]string>=v2Outgoing message
      messages[][status]string>=v2Message status
      messages[][dateTime]DateTime>=v2The date the message was created in UTC

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      202
      • Returned when message(s) saved successfully and added to queue
      400
      • Returned when input validation failed
      402
      • Returned when account is out of credits
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/sms{id}
    • DELETE /v2/sms{id} stable since v2

      Documentation

      Delete outgoing message

      Requirements

      NameRequirementTypeDescription
      number\d+integerOutgoing message id

      Status Codes

      Status CodeDescription
      204
      • Returned when message deleted successfully
      403
      • Returned when the user is not authorized
      404
      • Returned when sms outgoing is not found
      405
      • Method not allowed
    • GET /v2/sms{id} stable since v2

      Documentation

      View details of an outgoing message

      Requirements

      NameRequirementTypeDescription
      id\d+integerid or outgoing_id

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2Message part identifier
      outgoing_idinteger>=v2Outgoing message identifier
      originstring>=v2Where the SMS appears to come from. 4-11 characters A-Za-z0-9 if alphanumeric; 4-15 digits if numeric (if set, set sharedPool to null)
      destinationstring>=v2Destination mobile number. 4-15 digits
      messagestring>=v2Outgoing message
      statusstring>=v2Message status
      dateTimeDateTime>=v2The date the message was created in UTC

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
        Returned when the user does not allow to view the sms
      404
      • Returned when the user is not found
        Returned when something else is not found
      405
      • Method not allowed
  • sms-incoming
    /v2/sms-incoming
    • GET /v2/sms-incoming stable since v2

      Documentation

      View list of incoming messages

      Filters

      NameInformation
      offsetRequirement \d+
      Description Pagination offset (default 1, maximum offset + limit = 10,000)
      Default 1
      limitRequirement \d+
      Description Number of items to return (default 20, maximum 1000)
      Default 20
      startDateRequirement \d+
      Description Start date of the date range filter. Date format in account timezone
      endDateRequirement
      Description End date of the date range filter. Date format in account timezone
      destinationRequirement \d+
      Description The shared pool or dedicated number which the sms was sent to
      originRequirement \d+
      Description The number where the SMS appears to come from
      searchRequirement \d+
      Description Search string in source, destination and message

      Return

      ParameterTypeVersionsDescription
      totalinteger>=v2Total number of incoming message objects
      offsetinteger>=v2Pagination Offset (default 1)
      limitinteger>=v2Number of incoming message objects to return
      messages[]array of objects (SmsIncoming)>=v2A collection of incoming message objects
      messages[][id]integer>=v2Incoming message identifier
      messages[][origin]integer>=v2Where the SMS appears to come from
      messages[][destination]string>=v2The shared pool or dedicated number which the sms was sent to
      messages[][message]string>=v2The SMS message. If longer than 160 characters (GSM) or 70 characters (Unicode), splits into multiple SMS
      messages[][isUnicode]boolean>=v2If incoming message contains Unicode characters
      messages[][dateTime]DateTime>=v2The date and time this message was received
      messages[][campaign]object (Campaign)>=v2The campaign the message is associated with (optional)
      messages[][campaign][id]integer>=v2Campaign identifier
      messages[][isMultipart]boolean>=v2Whether the message exceeded the maximum length and had to be split into multiple parts
      messages[][partNumber]integer>=v2If concatenated, the part number this SMS represents; otherwise 1
      messages[][totalParts]integer>=v2If concatenated, the total number of parts in this SMS. Ranges from 1-255

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/sms-incoming/{id}
    • DELETE /v2/sms-incoming/{id} stable since v2

      Documentation

      Delete incoming message

      Requirements

      NameRequirementTypeDescription
      id\d+integerIncoming message id

      Status Codes

      Status CodeDescription
      204
      • Returned when message deleted successfully
      403
      • Returned when the user is not authorized
      404
      • Returned when sms incoming message is not found
      405
      • Method not allowed
    • GET /v2/sms-incoming/{id} stable since v2

      Documentation

      View details of a incoming message

      Requirements

      NameRequirementTypeDescription
      id\d+integerIncoming message id

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2Incoming message identifier
      originstring>=v2Where the SMS appears to come from
      destinationstring>=v2The shared pool or dedicated number which the sms was sent to
      messagestring>=v2The SMS message. If longer than 160 characters (GSM) or 70 characters (Unicode), splits into multiple SMS
      isUnicodeboolean>=v2If incoming message contains Unicode characters
      dateTimeDateTime>=v2The date and time this message was received
      campaignobject (Campaign)>=v2The campaign the message is associated with (optional)
      campaign[id]integer>=v2Campaign identifier
      isMultipartboolean>=v2Whether the message exceeded the maximum length and had to be split into multiple parts
      partNumberinteger>=v2If concatenated, the part number this SMS represents; otherwise 1
      totalPartsinteger>=v2If concatenated, the total number of parts in this SMS. Ranges from 1-255

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      404
      • Returned when sms incoming message is not found
      405
      • Method not allowed
  • user
    /v2/user/billing-details
    • GET /v2/user/billing-details stable since v2

      Documentation

      Get the authenticated account's billing details.

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2
      namestring>=v2The account holder's full name.
      phonestring>=v2The account holder's phone number.
      emailstring>=v2The account holder's email address.
      addressstring>=v2The account holder's address.
      citystring>=v2The account holder's city.
      statestring>=v2The account holder's state.
      postcodestring>=v2The account holder's postcode.
      countrystring>=v2The account holder's country.

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    • PUT /v2/user/billing-details stable since v2

      Documentation

      Update the authenticated account's billing details.

      Parameters

      ParameterTypeRequired?FormatDescription
      idintegertrue
      namestringtrueThe account holder's full name.
      phonestringtrueThe account holder's phone number.
      emailstringtrueThe account holder's email address.
      addressstringtrueThe account holder's address.
      citystringtrueThe account holder's city.
      statestringtrueThe account holder's state.
      postcodestringtrueThe account holder's postcode.
      countrystringtrueThe account holder's country.

      Status Codes

      Status CodeDescription
      204
      • Returned when successful
      400
      • Returned when the request is bad
      402
      • Returned when account is out of credits
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/user/contact-details
    • GET /v2/user/contact-details stable since v2

      Documentation

      Get the authenticated account's contact details.

      Return

      ParameterTypeVersionsDescription
      idinteger>=v2
      namestring>=v2The account holder's full name.
      phonestring>=v2The account holder's phone number.
      emailstring>=v2The account holder's email address.
      addressstring>=v2The account holder's address.
      citystring>=v2The account holder's city.
      statestring>=v2The account holder's state.
      postcodestring>=v2The account holder's postcode.
      countrystring>=v2The account holder's country.

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    • PUT /v2/user/contact-details stable since v2

      Documentation

      Update the authenticated account's contact details.

      Parameters

      ParameterTypeRequired?FormatDescription
      idintegertrue
      namestringtrueThe account holder's full name.
      phonestringtrueThe account holder's phone number.
      emailstringtrueThe account holder's email address.
      addressstringtrueThe account holder's address.
      citystringtrueThe account holder's city.
      statestringtrueThe account holder's state.
      postcodestringtrueThe account holder's postcode.
      countrystringtrueThe account holder's country.

      Status Codes

      Status CodeDescription
      204
      • Returned when successful
      400
      • Returned when the request is bad
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/user/credit-balance
    • GET /v2/user/credit-balance stable since v2

      Documentation

      View the account balance

      Return

      ParameterTypeVersionsDescription
      balancedouble>=v2Account Credit Balance (available for Pre-paid customers)
      currencystring>=v2Currency Code

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      404
      • Returned when the user is Post-Paid user
      405
      • Method not allowed
    /v2/user/low-balance-alerts
    • GET /v2/user/low-balance-alerts stable since v2

      Documentation

      Get the low balance alerts information associated to the authenticated account.

      Return

      ParameterTypeVersionsDescription
      enabledboolean>=v2Whether to send low balance alerts.
      thresholdinteger>=v2The low balance alerts threshold amount.
      sendtostring>=v2The low balance alerts contact delivery destination.

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    • PUT /v2/user/low-balance-alerts stable since v2

      Documentation

      Update the authenticated account's billing details.

      Parameters

      ParameterTypeRequired?FormatDescription
      enabledbooleantrueWhether to send low balance alerts.
      thresholdintegertrueThe low balance alerts threshold amount.
      sendtointegertrueThe low balance alerts contact delivery destination.

      Status Codes

      Status CodeDescription
      204
      • Returned when successful
      400
      • Returned when the request is bad
      402
      • Returned when account is out of credits
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/user/sub-account
    • POST /v2/user/sub-account stable since v2

      Documentation

      Create sub account

      Return

      ParameterTypeRequired?FormatDescription
      namestringtrueThe sub account's display name.
      emailstringtrueThe sub account's email address.
      passwordstringtrueThe sub account's password.
      mobilestringtrueThe sub account's mobile number.

      Status Codes

      Status CodeDescription
      201
      • Returned when successful
      400
      • Returned when the request is bad
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/user/verified-numbers
    • GET /v2/user/verified-numbers stable since v2

      Documentation

      Get the authenticated account's verified numbers.

      Return

      ParameterTypeVersionsDescription
      numbersarray>=v2

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
Loading Form