|
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.
|
|
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.
|
|
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.
|
|
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".
|
|
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.
|
|
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.
|
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.
|
|
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.
|
