SMSified is shutting down on May 31st 2014. All accounts are valid on Tropo.com, so users can use their same account and migrate their application to Tropo scripting. If you have any questions, or need assistance, please contact support@tropo.com

API Reference

Parameters

Sending

address The telephone number of the recipient. Must include the country code in the number, i.e. 14075551212, not 4075551212. This parameter is required.
senderAddress This is the number used to send the text message - it's included in the URL directly; it must be a number tied to your account. This parameter is required.
message The text content to send to the recipient. This parameter is required.
notifyURL If you want SMSified to send you status information about the sent SMS, you can set the preferred destination URL here. This parameter is optional.
callbackData If you want some additional custom information to pass to the URL defined by notifyURL, you can add it here; the field is limited to 1024 characters. This parameter is optional.
clientCorrelator This field allows you to prevent duplicate messages from sending - if you define the same clientCorrelator for every SMS, and you attempt to send a message with the same address & message, the request will fail with a "400 Bad Request" Response Code. This parameter is optional.
resourceURL This is the URL returned when an SMS is successfully sent. It contains the requestId at the very end, which can be used to view the status of all messages sent by that request.

Receiving

message The text content sent to the recipient.
destinationAddress The telephone number of the recipient.
senderAddress The phone number used to send the text message.
messageId The unique ID associated with each text message.

Callbacks & Status

address The telephone number of the recipient.
senderAddress The phone number used to send the text message.
createdDateTime The datetime the message was created.
sentDateTime The datetime the message was actually sent. This can be delayed due to message queuing if rate limits are exceeded.
code Value will be “0” if the message is successfully sent; for the list of potential messages you might see with a failure, please see the section on SMS Status Codes.
message The text content sent to the recipient.
messageId The unique ID associated with each text message.
deliveryStatus Identifies the success or failure of an SMS. Exact possible values are:

  • DeliveryUncertain (delivery status unknown, typically because the message was handed off to another network)
  • DeliveryImpossible (unsuccessful delivery - the message could not be delivered before it expired)
  • DeliveredToNetwork (successful delivery to the network enabler - responsible for routing the SMS)
  • MessageWaiting (the message is still queued for delivery - this is a temporary state, pending transition to one of the preceding states)
  • parts This indicates whether the contents of the SMS were completely contained in one message (160 characters or less) or needed to be split into more than one.

    Subscriptions

    senderAddress Identifies the telephone number you're linking the URL when creating an outbound subscription. This parameter is required.
    destinationAddress Identifies the telephone number you're linking the URL when creating an inbound subscription. This parameter is required.
    notifyURL If you want SMSified to send you status information about the sent SMS, you can set the preferred destination URL here. This parameter is required.
    callbackData If you want some additional custom information to pass to the URL defined by notifyURL, you can add it here; the field is limited to 1024 characters. This parameter is optional.
    criteria This is used with inbound subscriptions and short codes; it's essentially a keyword you can use to set up independent subscriptions to the same short code. This parameter is optional.
    clientCorrelator This field allows you to prevent duplicate subscriptions from being created - if you define the same clientCorrelator when creating subscriptions, and you attempt to create a subscription with the same phone number and notifyURL, the request will fail with a "400 Bad Request" Response Code. This parameter is optional.
    resourceURL This is the URL returned when a subscription is successfully created. It contains the subscriptionId at the very end, which is used if you need to delete the subscription later on.
    subscriptionId This is the unique ID used to identify the subscription.
    notificationFormat This identifies the format of the data sent to the URL; this will always be JSON.

    Reporting

    messageId The unique ID associated with each text message.
    body The text content sent to the recipient.
    to The telephone number of the recipient.
    from The callerID displayed on the recipient’s phone.
    status Identifies the success or failure of an SMS. Exact possible values are "success" or "fail".
    direction Defines whether the text message was inbound or outbound. Exact possible values are "in" or "out".
    created The timestamp the message was created.
    sent The timestamp the message was sent.
    parts This indicates whether the contents of the SMS were completely contained in one message (160 characters or less) or needed to be split into more than one.
    startDate This is used in the URL for a report and defines the starting date of a date range filter. Format is yyyy-mm-dd, like 2011-02-01.
    endDate This is used in the URL for a report and defines the ending date of a date range filter. Format is yyyy-mm-dd, like 2011-02-01.
    pageSize This is used in the URL for a report and defines how many records to display per page. Accepts digits only, such as 1, 2, 3.
    pageNumber This is used in the URL for a report and defines which page, out of the total amount of pages, is displayed in the response body. Accepts digits only, such as 1, 2, 3.
    orderDirection This is used in the URL for a report and defines whether the data is sorted ascending or descending by the sent date. By default, this is set to descending. Possible values are "desc" or "asc".

    Reporting Headers

    X-Api-Version This displays the version of SMSified being used.
    Page-Number This displays the page number being viewed - if it isn't defined, this will display as 0.
    Total-Pages This displays the total amount of pages containing records, which is determined by the pageSize. By default, pageSize is 50.
    Total-Records This displays the total amount of records in the report.
    Start-Index This displays which record, out of the total number of records, is listed first on the page being viewed. On the first page, this will be 0.
    End-Index This displays which record, out of the total number of records, is listed last on the page being viewed.
    Records-Per-Page This displays the total amount of records set to display on each page.
    Content-Type This displays the content-type returned - it can be JSON, XML or form-encoded.
    Date This displays the date the report was pulled.

    HTTP Response Codes

    200 OK A subscription was successfully created or a reporting request was successful.
    201 Created The message was sent (this does not mean delivery was successful, just that the request to SMSified to send the message was successful).
    204 No Content This is returned if the DELETE of a subscription was successful.
    400 Bad Request Something is wrong with the syntax of your request, such as a malformed request body or invalid parameter names. You will also get a 400 if you use a clientCorrelator and attempt to send a duplicate message or create duplicate subscriptions. If you get a 400, SMSified also provides additional error information in the form of exceptions - check out the Service & Policy Exceptions section for more details.
    401 Unauthorized You did not include a username/password with the request or your credentials are incorrect.
    404 Not Found The URL you're attempting to use to send an SMS is invalid. This can be caused by a simple typo, i.e. "/request" instead of "/requests", or this can also be returned if you attempt to GET a message's delivery info, but the message ID is invalid.
    405 Method Not Allowed You're attempting to use a method that isn't supported, such as a DELETE on "https://api.smsified.com/1/smsmessaging/outbound/{senderAddress}/requests"
    415 Unsupported Media Type You're trying to send a text message but the Content-Type header is set to something other than x-www-form-urlencoded, such as text/xml.
    500 Internal Error This indicates an error has occurred on the SMSified servers, as opposed to anything wrong with your code. Contact technical support as soon as possible.
    503 Service Unavailable The server is unavailable, possibly overloaded or down for maintenance. Please wait a few moments and try again; if the issue persists, contact support.

    Service & Policy Exceptions

    When you receive a "400 Bad Request" Response Code (and in a more limited form, 404 and 405 Response Codes as well), SMSified will provide some additional detailed error information to help you determine the cause.

    SVC0001 A service exception has occurred, the details of the error will be in the message (typically tied to 404 and 405 response codes)
    SVC0002 A required parameter (such as address when sending a text message) is missing, so the request cannot be completed.
    SVC0004 No valid addresses were provided in the request - addresses means phone numbers, so this would be returned if the phone numbers are too short or encoded incorrectly.
    SVC0005 You're using a clientCorrelator and it's blocking the duplicate creation of an SMS or a subscription.
    POL0001 The URL you're attempting to use to send an SMS is invalid. This can be caused by a simple typo, i.e. "/request" instead of "/requests", or this can also be returned if you attempt to GET a message's delivery info, but the messageId is invalid.
    POL0014 The number you're attempting to use as your senderAddress is not a number on your account (numbers on your account are considered the "white list")
    POL0015 The number you're attempting to send to is on a "black list" (blocked numbers), such as 911.
    POL0020 The length of a field has been exceeded, typically 1024 characters except for message length, which is limited to 2048.

    SMS Status Codes

    0 "Delivered" - The message was successfully delivered to the carrier.
    -1 "Bad or Unsupported Phone Number" - The number you're attempting to send to is invalid, either because it's incorrectly formatted (missing the +1 in front of the number) or in an unsupported service area (outside the U.S.)
    -2 "Carrier Error" - An error has occurred at the carrier level - contact technical support to investigate further.
    -3 "Gateway Error" - An error has occurred at the gateway level - contact technical support to investigate further.
    -4 "Exceeded Rate Limit" - The amount of SMS messages sent in a given time has exceeded the 10 messages per minute limit imposed by the carrier for long codes pr 40 messages per second in place for short codes.
    -5 "Duplicate Message" - Carriers block duplicate messages if they're sent within a minute of each other. Duplicate message means the same destination address, sender address and message body; this is intended to prevent spam or malicious attacks.
    -6 "Expired" - The inbound or outbound message could not be delivered and was dropped after 4 hours worth of attempts.
    -7 "Blocked" - The text message contains forbidden content or the destination phone number is on an opt-out list and the message was rejected. Forbidden content is covered in FAQ, under the header "When should I use a short code or a long code?".
    -10 "Bad URL" - The text message was received by SMSified, but the content was unable to be delivered to the defined URL, likely because the URL is invalid. This applies to inbound only.
    -11 "Delivery failed" - There's an inbound subscription associated with the number, but the POST to the URL fails. This applies to inbound only.
    -99 "Unknown" - An unknown error has occurred, contact technical support to investigate further.