Http Status Code |
Sently Plus Error Code |
Description |
Scenario |
Resolution |
500 |
10001 |
Error creating token |
The token could not be created in the underlying data storage |
May be due to network issues. Try again later |
403 |
10002 |
Invalid access token |
The token could not be validated |
Go through the token issuing flow again to obtain a new token |
400 |
10002 |
Token was missing in the request |
Authorization header does not contain token |
Authorization header value must be: Bearer <token> |
400 |
10003 |
Request needs HTTPS |
An attempt was made to access API using HTTP |
Reissue request using HTTPS |
500 |
10004 |
Error setting security principal |
We could not set the security context for your token |
Contact administrator |
500 |
10005 |
Error issuing token |
We could not create a token in the underlying storage |
Try again later. If problem persists, contact administrator |
403 |
10006 |
Invalid credentials |
We could not validate the supplied credentials |
Send the correct credentials and try again |
400 |
10007 |
Request does not contain Authorization header |
A request was made to API without Authorization header present |
Send the request with the Authorization header present |
403 |
10008 |
Could not authenticate request |
The request could not be authenticated via an access token |
Go through token issuing flow again and try again with the new token |
400 |
10009 |
Body missing grant_type |
The body of the request must be: grant_type=client_credentials |
Reissue request with grant_type=client_credentials present in body |
400 |
10010 |
Body missing access token |
Body must contain
access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA... |
Reissue request with access_token present in body |
400 |
10011 |
Base64 decoding failed |
Error while decoding your Base64 encoded credentials string |
Make sure that your Base64 encoding is correct. See Wikipedia |
400 |
10012 |
Message has incorrect number of parts |
Error while splitting credentials with : |
Make sure that you concatenate the credentials before Base64 encoding in the form consumerSecret:consumerKey |
400 |
10013 |
Url decoding failed |
Error while url decoding consumerSecret or consumerKey |
Make sure that you correctly URL encode cedentials before concatenating with ':' and Base64 encoding them. |
400 |
10014 |
Error calling underlying resource API |
Authentication suceeded, but calling the underlying resource API resulted in an uncaught exception |
If the problem persists, contact administrator |
**Example of a security wrapper error response**
HTTP/1.1 403 Forbidden
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Thu, 23 May 2013 15:13:05 GMT
Content-Length: 123
{"errorMessage":"Please authenticate by a request to /api/token before calling any API methods","errorType":1,"errorCode":10008}
Note the non 200 HTTP Status code and "errorType":1 which indicate that this is a security wrapper error and not an API error.
**Example of an API error response**
All API error responses have a HTTP status code of 200. We will show an example of just one error response that
results while trying to retrieve a list with an id that does not exist. Specific errors related to resources will
be discussed when we discuss the resource API. The error response from a resource API error (and **NOT** from the
security wrapper layer) is shown below:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Thu, 23 May 2013 16:09:11 GMT
Content-Length: 90
{"errorMessage":"The specified list does not exist.","errorCode":5005,"responseData":null}
One should note that the HTTP status code for this response was 200 and hence it is an resource API error specified
by the API error code in the 5000 range. A detailed discussion of 5000 range API codes will ensue when we talk
about Resource APIs later.
---
--
Token
This portion of the API pertains to obtaining a bearer token from the Security Wrapper. The bearer token thus
obtained is passed in the
Http Status Code |
Sently Plus Error Code |
Description |
Scenario |
Resolution |
200 |
5004 |
Column already exists |
Another column exists with the same name as specified in the renameTo value |
Provide another column name in the request and try again |
200 |
5005 |
List does not exist |
The list specified by the provided id does not exist |
Provide a valid id in the request and try again |
200 |
5006 |
Column does not exists |
The specified column to rename was not found in the list |
Provide a valid column name in the request and try again |
200 |
5030 |
Cannot rename mobile phone number column |
The mobile phone number column cannot be renamed |
Provide a valid column name in the request and try again |
PUT /api/listschema
> Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
> Content-Type: application/json
{
"listId":"69fa1030-f37b-4f1b-acee-31a3addf84c1",
"name":"Address",
"renameTo":"Home Address"
}
< 200
< Content-Type: application/json
{
"errorMessage":"",
"errorCode":0,
"responseData":null
}
Deletes the specified column from the specified list. All data for that column will be cleared!
The following table lists errors that may occur as a result of this call:
Http Status Code |
Sently Plus Error Code |
Description |
Scenario |
Resolution |
200 |
5005 |
List does not exist |
The list specified by the provided id does not exist |
Provide a valid id in the request and try again |
200 |
5007 |
List items not present |
We could not detect any posted items |
Please make sure that there are one or more items present in the request body |
200 |
5008 |
List data validation failed |
One or more of the posted items has data errors |
Please check the responseData key for the Errors array (see the example above) to see which items had errors.
You may post the items again after correcting the specified errors.
|
200 |
5010 |
List schema validation failed |
You have probably specified the value for a column that does not exist |
Please check the responseData key for the Errors array (see the example above) to see which items had errors.
You may post the items again after correcting the specified errors.
|
200 |
5019 |
Database Error |
An error ocurred while saving the items |
Please check the errorMessage key for what may have gone wrong. If the problem persists, please contact administrator.
|
200 |
5022 |
Duplicate Custom Id |
You are trying to insert an item in a list which has another item already present with the same Custom Id |
Please provide a different Custom Id for the item and try again.
|
POST /api/listitem
> Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
> Content-Type: application/json
{
"listId":"69fa1030-f37b-4f1b-acee-31a3addf84c1",
"items":[
{
"CustomId":"1234",
"rowData":{
"First Name":"Adam",
"Last Name":"Smith",
"Mobile Phone Number":"+6583888388"
}
},
{
"CustomId":null,
"rowData":{
"First Name":"Albert",
"last NaMe":"Einstein",
"Mobile Phone Number":"+6583998399"
}
}
],
"clientDate":"2013-05-24T19:54:44.2543217+08:00"
}
< 200
< Content-Type: application/json
{
"errorMessage":"",
"errorCode":0,
"responseData":{
"listItems":[
{
"MobilePhoneNumber":"+6583888388",
"Id":"1234"
},
{
"MobilePhoneNumber":"+6583998399",
"Id":"f9794af3-d752-4941-a1ee-af5af3987764"
}
]
}
}
Given a Custom Id and a list of column names and their values, this method will change the values of those
columns in all lists that contain the specified columns. In the example below, the name "Albert" will be
changed to "Bertie" in all lists that contain a column called "First Name" (case insensitive), the phone
number will also be changed by the same logic.
The following table lists errors that may occur as a result of this call:
Http Status Code |
Sently Plus Error Code |
Description |
Scenario |
Resolution |
200 |
5005 |
List does not exist |
The list specified in the request could not be found |
Provide a valid Id for the list in the request and try again |
200 |
5006 |
List field does not exist |
A list field specified in the campaign text could not be found |
Check the error message to see which field is invalid. Provide a valid field name in the campaign
text and try again.
|
200 |
5014 |
Identity does not exist |
The identity specified in the request could not be found |
Provide a valid Id for the identity in the request and try again |
200 |
5016 |
Duplicate campaign name |
Campaigns must have unique names |
Provide another campaign name and try again |
200 |
5024 |
Campaign name is mandatory |
A campaign name must be specified in the request |
Provide a valid and unique campaign name in the request and try again |
200 |
5025 |
Campaign text is mandatory |
Campaign text must be specified in the request |
Provide a valid string for the campaign text in the request and try again |
POST /api/campaign
> Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
> Content-Type: application/json
{
"campaignText":"hello world via api *|Mobile phone number|*",
"campaignName":"Api campaign 6",
"campaignIdentity":"f798b4e8-7510-431f-9928-7838cc75097d",
"campaignList":"3b159568-cf58-41ea-b9f27f6ae5dd0732",
"callbackUrl":"http://yourserver.com/callback",
"isUnsubscribeEnabled":false
}
< 200
< Content-Type: application/json
{
"errorMessage":"",
"errorCode":0,
"responseData":{
"Id":52
}
}
Changes the campaign specified by the campaign id.
The following table lists errors that may occur as a result of this call:
Http Status Code |
Sently Plus Error Code |
Description |
Scenario |
Resolution |
200 |
5005 |
List does not exist |
The list specified in the request could not be found |
Provide a valid Id for the list in the request and try again |
200 |
5006 |
List field does not exist |
A list field specified in the campaign text could not be found |
Check the error message to see which field is invalid. Provide a valid field name in the campaign
text and try again.
|
200 |
5013 |
Cannot modify campaign |
The campaign sending may be already be in progress |
Campaigns that are currently being sent or need to be sent within the next 1 minute cannot be modified. |
200 |
5014 |
Identity does not exist |
The identity specified in the request could not be found |
Provide a valid Id for the identity in the request and try again |
200 |
5016 |
Duplicate campaign name |
Campaigns must have unique names |
Provide another campaign name and try again |
200 |
5024 |
Campaign name is mandatory |
A campaign name must be specified in the request |
Provide a valid and unique campaign name in the request and try again |
200 |
5025 |
Campaign text is mandatory |
Campaign text must be specified in the request |
Provide a valid string for the campaign text in the request and try again |
PUT /api/campaign
> Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
> Content-Type: application/json
{
"campaignId": 52,
"campaignText":"hello world via api *|Mobile phone number|*",
"campaignName":"Api campaign 7",
"campaignIdentity":"f798b4e8-7510-431f-9928-7838cc75097d",
"campaignList":"3b159568-cf58-41ea-b9f27f6ae5dd0732",
"isUnsubscribeEnabled":false
}
< 200
< Content-Type: application/json
{
"errorMessage":"",
"errorCode":0,
"responseData":{
"isCreditTopupNeeded":false,
"campaign":{
"Id":52,
"ListId":"3b159568-cf58-41ea-b9f2-7f6ae5dd0732",
"Text":"hello world via api *|Mobile phone number|*",
"SuppressUnsubscribe":true,
"SupressHeader":false,
"UserId":20,
"CampaignName":"Renamed campaign",
"DateCreated":"2013-05-26T12:08:53.957",
"DateModified":"2013-05-26T12:30:10.64289Z",
"SenderId":"98051602-2401-4d87-b210-d3d826b0ac4f",
"UnsubscribeTemplate":"Unsubscribe - /u?protocol=http/{0}",
"CallbackUrlTemplate":"/d?protocol=http/{0}"
}
}
}
Delete the specified campaign
The following table lists errors that may occur as a result of this call:
Status | Meaning | Description |
0 | None | Unused |
1 | Pending | The job has been added to the queue and processing will start at the
date and time specified while creating the job |
2 | Calculating cost | The job is being processed. We are going through all the recipients and
constructing messages based on the template specified in the campaign text. Based on the text thus created,
we are calculating the number of credits required for the job. |
3 | Queueing and sending | The job is being processed. We are adding messages to the send queue
and are in the process of sending messages out |
4 | Sending | The job is being processed. All messages have been queued, we are in the process
of sending them out |
5 |
Completed |
All messages have been sent to gateway. The sent, delivery, failure and unsubscribe counts will
still change as we track messages as they are sent from the gateway and delivered to a handset. |
6 |
Failed |
Something went wrong while sending your campaign. Contact administrator if the problem persists. |
The dates returned in the response are UTC date/time.
If the job status is 6 (Failed), then then the failure reason will be specified. The following table lists
the codes for this and their meaning:
Failure reason code |
Meaning |
Scenario |
Resolution |
0 |
None |
Unused |
N/A |
1 |
Failed to Queue |
There was an error while trying to queue messages for this job. |
Please try creating another job. If the problem persists, contact adminstrator. |
2 |
Job too big |
The list specified for this campaign job has too many recipients |
Please try creating another job using a smaller list. If the problem persists, contact adminstrator. |
3 |
Insufficient credits |
This job was abandoned as there were insufficient credits in your account to send this campaign |
Please topup credits and try again |
4 |
List Deleted |
The list specified by the campaign no longer exists |
Please ensure that the campaign contains a valid list and try again |
5 |
Campaign Deleted |
The campaign specified for the job no longer exists |
Please ensure that the campaign job contains a valid campaign and try again |
6 |
Identity Deleted |
The identity specified by the campaign no longer exists |
Please ensure that the campaign contains a valid identity and try again |
GET /api/campaignjob
> Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
< 200
< Content-Type: application/json
{
"errorMessage":"",
"errorCode":0,
"responseData":[
{
"Id":42,
"CampaignId":51,
"ListId":"3b159568-cf58-41ea-b9f2-7f6ae5dd0732",
"DateScheduled":"2013-05-27T07:56:25.007",
"Status":1,
"CreditsNeeded":0,
"MessagesSent":0,
"MessagesDelivered":0,
"MessagesFailed":0,
"FailureReason":null,
"DateUpdated":"2013-05-27T05:26:25.053",
"IsCreditDeductionDone":false,
"MessagesUnsubscribed":0
},
{
"Id":41,
"CampaignId":51,
"ListId":"3b159568-cf58-41ea-b9f2-7f6ae5dd0732",
"DateScheduled":"2013-05-27T07:52:23.65",
"Status":1,
"CreditsNeeded":0,
"MessagesSent":0,
"MessagesDelivered":0,
"MessagesFailed":0,
"FailureReason":null,
"DateUpdated":"2013-05-27T05:22:23.707",
"IsCreditDeductionDone":false,
"MessagesUnsubscribed":0
},
{
"Id":40,
"CampaignId":51,
"ListId":"3b159568-cf58-41ea-b9f2-7f6ae5dd0732",
"DateScheduled":"2013-05-23T08:56:45.017",
"Status":1,
"CreditsNeeded":0,
"MessagesSent":0,
"MessagesDelivered":0,
"MessagesFailed":0,
"FailureReason":null,
"DateUpdated":"2013-05-23T06:26:45.047",
"IsCreditDeductionDone":false,
"MessagesUnsubscribed":0
}
]
}
Gets the specified campaign. See the other GET method documentation for an explanation of Status and Failure
reasons.
The following table lists errors that may occur as a result of this call:
Http Status Code |
Sently Plus Error Code |
Description |
Scenario |
Resolution |
200 |
5012 |
Take/skip parameters missing |
The request did not have take/skip query string parameters |
Provide take and skip parameters and try again |
200 |
5021 |
Failed to parse take/skip |
The specified take/skip parameters were not valid integers |
Provide a valid values for take/skip in the request query string and try again |
200 |
5027 |
Failed to find specified number of failed messages |
This could be a result of skipping over too many items or specifying an incorrect campaign job id |
Adjust the parameters in the request and try again |
GET /api/failedmessages/1?take=50&skip=0
> Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
< 200
< Content-Type: application/json
{
"errorMessage":"",
"errorCode":0,
"responseData":{
"CampaignJobId":1,
"Items":[
{
"Mobile phone number":"+6583888388",
"First Name":"Adam",
"Last Name":"Smith",
"IsUnsubscribed":"False",
"IsBouncing":"False",
"DateFlagged":"2013-01-04 16:19:19",
"IsUnsubscribedDueToCampaign":"True",
"IsFailedDueToCampaign":"False"
}
]
}
}
--
SMS
This resource can be used to shoot out a message to up to a 100 recipients without explicitly
creating a list or campaign. Internally this resource does create temporary lists, campaigns
and jobs, but these temporary structures are automatically cleared at the end of the month.
--
Post the list of messages to send.
The following table describes the parameters in the request:
Parameter |
Meaning |
phoneNumbers |
List of phone number the message will be sent to. Cannot be more than 100 numbers in this list |
description |
A description that will show in the UI to help track this request |
message |
Message to send to the specified receipients |
senderId |
The Id of the identity that the message will apear to be sent from |
callbackUrl |
If this URL is specified, it will be hit with jobid, smsid, status in the query string parameters. Allowing you to track the message in near real time. |
sendWhenMilliseconds |
If this is not zero, the message will be sent after the specified number of milliseconds from the time the API call is made |
clientDate |
This should be the current time in your time zone. It is used to calculate time zone offset from your time zone while dealing with dates |
isUnsubscribeEnabled |
If this is set to true, an unsubscribe link will be included in the messages that are sent out |
Http Status Code |
Sently Plus Error Code |
Description |
Scenario |
Resolution |
200 |
5008 |
List data validation failed |
One or more of the posted items has data errors |
Please check the responseData key for the Errors array (see the list item resource) to see which items had errors.
You may post the items again after correcting the specified errors.
|
200 |
5014 |
The identity specified in senderId was not found |
No identities were found that matched the specified senderId |
Please provide a valid senderId in the request |
200 |
5019 |
Database Error |
An error ocurred while saving the items |
Please check the errorMessage key for what may have gone wrong. If the problem persists, please contact administrator.
|
200 |
5028 |
One or more phone numbers must be supplied |
The request did not have any phone numbers |
Provide a list of phone numbers and try again |
200 |
5029 |
Too many phone numbers in the request |
The specified request has too many phone numbers |
Break down your list and send 100 numbers at a time and try again |
POST /api/sms
> Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
> Content-Type: application/json
{
"phoneNumbers":[
"+6583887908",
"+6598509388"
],
"description":"API Test",
"message":"Hello From the API",
"senderId":"e85318eb-e085-4f38-93a09e4636c06c35",
"callbackUrl":"http://url.sent.ly/",
"sendWhenMilliseconds":0,
"clientDate":"2013-06-18T15:51:43.3625565+08:00",
"isUnsubscribeEnabled":true
}
< 200
< Content-Type: application/json
{
"errorMessage":"",
"errorCode":0,
"responseData":{
"campaignJobId":19,
"listItems":[
{
"MobilePhoneNumber":"+6583887908",
"Id":"012d01ad-7734-435c-960b-39ef1e23c664"
},
{
"MobilePhoneNumber":"+6598509388",
"Id":"14729a49-0ee2-4661-acd8-229b53dd98ca"
}
]
}
}