SITCA A.P.I. Documentation

Version 1.1.0

Choose from the menu to review A.P.I. details

Methods

There are six (6) functions/methods that are possible through the SITCA AdvancedSMS API. They are:

  • BALANCE
    Use this function to determine your real-time balance which will be expressed in XCD (Eastern Caribbean Currency). Click above for more details

  • CANCEL
    Use this function to cancel an existing broadcast. You will need a reference-code to identify which broadcast to cancel. Click above for more details.

  • EMPTYPHONEBOOK
    Use this function to delete all telephone numbers associated with your account. Click above for more details.

  • HISTORY
    Use this function to get historic data of a broadcast. This data will be in the form of a Microsoft Excel file accessible via a link that is returned in the request. Click above for more information.

  • SCHEDULE
    Use this function to schedule broadcasts. Include the numbers you want to broadcast to and your message. Click above for more details

  • STATUS
    Use this function to determine summary information about a broadcast, such as when it started/ended as well as how many messages have been sent and how many are remaining. Click above for more details.

Home | Methods

Balance

Title

Get real-time balance

URL

/api

Method

POST

Data Params

Example: 

    
        {
            apiKey    : [string],
            apiSecret : [string],
            command : "balance",
        }
Example: 

        {
            apiKey    : "K830291KE",
            apiSecret : "38ekaldk3and!",
            command   : "balance"
        }
Success Response

Content:

    
        {
            status  : "00",
            details : "XCD $250.75"
        }
Possible Error Responses

Content: Bad Data, data supplied is invalid 

    
        {
         status  : "99"
        ,details : "Bad Data"
        }

Content: System Error
System error, contact SITCA

    
        {
         status  : "98"
        ,details : "System Error, contact SITCA for support"
        ,referenceCode : "1286705410"
        }
Sample Call 

        $.ajax({
            url: "https://www.sitcaribbean.com/api"
            ,dataType: "json"
            ,data :
                {
                     apiKey    : "K830291KE"
                    ,apiSecret : "38ekaldk3and!"
                    ,command   : "balance"
                }
        });
Notes

In the event of a System Error, ensure you include in your support call/email the reference-code that was returned

Home | Methods

History

Title

Get the history of a broadcast as it relates to delivery status
URL

/api

Method

POST

Data Params

 
    
        {
            apiKey    : [string]
            ,apiSecret : [string]
            ,command : "history"
            ,referenceCode : [string]
        }

Example: 


        {
            apiKey    : "K830291KE"
            ,apiSecret : "38ekaldk3and!"
            ,command   : "history"
            ,referenceCode : "IEKDLWO!"
        }

Success Response

Content:

    
        {
            status  : "00"
            ,details : "https://www.sitcaribbean.com/Reports/HistoryReport_USERNAME_YYYYMMDD_HHMMSS.xlsx"
        }

Possible Error Responses

Content: Bad Data, data supplied is invalid 

    
        {
            status  : "99"
            ,details : "Bad Data"
        }

Content: System Error
System error, contact SITCA

    
        {
            status  : "98"
            ,details : "System Error, contact SITCA for support"
            ,referenceCode : "1286705410"
        }

Sample Call

 

        $.ajax(
        {
            url: "https://www.sitcaribbean.com/api"
            ,dataType: "json"
            ,data :
            {
                apiKey    : "K830291KE"
                ,apiSecret : "38ekaldk3and!"
                ,command   : "history"
                ,referenceCode : "IEKDLWO!"
            }
        });
Notes

In the event of a System Error, ensure you include in your support call/email the reference-code that was returned

Home | Methods

Empty Phone Book

Title

Delete all phone book entries from phone book

URL

/api

Method

POST

Data Params

Example:

 

        {
            apiKey     : [string]
            ,apiSecret : [string]
            ,command   : "emptyphonebook"
        }

Example: 


        {
            apiKey    : "K830291KE"
            ,apiSecret : "38ekaldk3and!"
            ,command   : "emptyphonebook"
        }
Success Response

Content:

Content:

    
        {
            status  : "09",
            details : "Phone book entries successfully removed"
        }
Possible Error Response(s)

Content: Bad Data, data supplied is invalid 

    
        {
            status  : "99"
            ,details : "Bad Data"
        }

Content: System Error
System error, contact SITCA

    
        {
            status  : "98"
            ,details : "System Error, contact SITCA for support"
            ,referenceCode : "1286705410"
        }
Sample Call 

        $.ajax(
        {
            url: "https://www.sitcaribbean.com/api"
            ,dataType: "json"
            ,data :
            {
                apiKey    : "K830291KE"
                ,apiSecret : "38ekaldk3and!"
                ,command   : "balance"
            }
        });
Notes

In the event of a System Error, ensure you include in your support call/email the reference-code that was returned

Home | Methods

Status

Title

Get the status of an already scheduled broadcast
URL

/api

Method

POST

Data Params

 
    
        {
            apiKey    : [string]
            ,apiSecret : [string]
            ,command : "status"
            ,referenceCode : [string]
        }

Example: 


        {
            apiKey    : "K830291KE"
            ,apiSecret : "38ekaldk3and!"
            ,command   : "status"
            ,referenceCode : "IEKDLWO!"
        }

Success Response

Content:

    
        {
         status  : "00"
        ,details :
            {
                DateStarted => '2015-03-15 19:15:00'
                ,DateEnded => ''
                ,AmountRemaining => 1500
                ,AmountSent => 7436
            }
        }

Possible Error Responses

Content: Bad Data, data supplied is invalid 

    
        {
            status  : "99"
            ,details : "Bad Data"
        }

Content: System Error
System error, contact SITCA

    
        {
            status  : "98"
            ,details : "System Error, contact SITCA for support"
            ,referenceCode : "1286705410"
        }

Sample Call

 

        $.ajax(
        {
            url: "https://www.sitcaribbean.com/api"
            ,dataType: "json"
            ,data :
            {
                apiKey    : "K830291KE"
                ,apiSecret : "38ekaldk3and!"
                ,command   : "status"
                ,referenceCode : "IEKDLWO!"
            }
        });
Notes

In the event of a System Error, ensure you include in your support call/email the reference-code that was returned

Home | Methods

Cancel Broadcast

Title

Cancel a scheduled or already running broadcast

URL

/api

Method

POST

Data Params

 
    
        {
            apiKey    : [string],
            apiSecret : [string],
            command : "cancel",
            referenceCode : [string]
        }

Example: 


        {
            apiKey    : "K830291KE"
            ,apiSecret : "38ekaldk3and!"
            ,command   : "cancel"
            ,referenceCode : "IEKDLWO!"
        }
Success Response

Content:

    
        {
            status  : "08",
            details : "Broadcast Cancelled"
        }
Possible Error Responses

Content: Bad Data, data supplied is invalid 

    
        {
            status  : "99"
            ,details : "Bad Data"
        }

Content: System Error
System error, contact SITCA

    
        {
            status  : "98"
            ,details : "System Error, contact SITCA for support"
            ,referenceCode : "1286705410"
        }
Sample Call 

        $.ajax(
        {
            url: "https://www.sitcaribbean.com/api"
            ,dataType: "json"
            ,data :
            {
                apiKey    : "K830291KE"
                ,apiSecret : "38ekaldk3and!"
                ,command   : "cancel"
                ,referenceCode : "IEKDLWO!"
            }
        });
Notes

In the event of a System Error, ensure you include in your support call/email the reference-code that was returned. Additionally, this immediately cancels the broadcast. You may want to get status in terms of how many messages were sent and remaining to be sent prior to issuing this command.

Home | Methods

Schedule a broadcast

Title

Schedule a broadcast

URL

/api

Method

POST

Data Params

 
    
        {
         apiKey    : [string]
        ,apiSecret : [string]
        ,command : "schedule"
        ,whenToSend : [string]
        ,messageFrom: [string]
        ,recipient:
            {
                {
                    number  : [string]
                    name    : [string]
                    group   : [string]
                    field01 : [string]
                    field02 : [string]
                    field03 : [string]
                    field04 : [string]
                    field05 : [string]
                    field06 : [string]
                    field07 : [string]
                    field08 : [string]
                    field09 : [string]
                    field10 : [string]
                }
            }
        }
        ,messageToSend : [string]
        ,notifyTelephone :
        {
            {[string]}
        }
        ,notifyEmail:
        {
            {[string]}
        }
        ,sendAcceptanceConfirmation : boolean
        ,expectReply : boolean
        }

Example: 


        {
        apiKey    : "K830291KE"
        ,apiSecret : "38ekaldk3and!"
        ,command   : "schedule"
        ,whenToSend : "2015-11-23 15:25:00"
        ,messageFrom: "AcmeLTD"
        ,recipient:
            {
                {
                    number  : "1268123456"
                    ,name    : "James Doe"
                    ,group   : "Everyone"
                    ,field01 : "Mr"
                    ,field02 : "Wednesday"
                    ,field03 : "10 AM"
                    ,field04 : "Mr Samuel"
                    ,field05 : "1-268-745-2546"
                    ,field06 : ""
                    ,field07 : ""
                    ,field08 : ""
                    ,field09 : ""
                    ,field10 : ""
                },
                {
                    number  : "12689874512"
                    ,name    : "Janice Doethy"
                    ,group   : "Everyone"
                    ,field01 : "Mrs"
                    ,field02 : "Tuesday"
                    ,field03 : "9 AM"
                    ,field04 : "Ms Spencer"
                    ,field05 : "1-268-745-2174"
                    ,field06 : ""
                    ,field07 : ""
                    ,field08 : ""
                    ,field09 : ""
                    ,field10 : ""
                },
                {
                    number  : "12687451247"
                    ,name    : "Jacob Doe"
                    ,group   : "Everyone"
                    ,field01 : "Mr"
                    ,field02 : "Friday"
                    ,field03 : "1 PM"
                    ,field04 : "Mr Smith"
                    ,field05 : "1-268-745-4196"
                    ,field06 : ""
                    ,field07 : ""
                    ,field08 : ""
                    ,field09 : ""
                    ,field10 : ""
                }
            }
        }
        ,messageToSend : "Hello [field01] [name]. This is just a gentle reminder for your appointment
                          next [field02] with [field04] at [field03].  If you need to reschedule please
                          call [field04] at any time at [field05]. Yours truly, Dr Smith"
        ,notifyTelephone :
        {
            {12687451123}
            ,{12687452174}
            ,{12687459684}
        }
        ,notifyEmail:
        {
            {"itsupport@drsmithantigua.com"}
            ,{"drsmith@drsmithantigua.com"}
            ,{"frontdesk@drsmithantigua.com"}
        }
        ,sendAcceptanceConfirmation : 1
        ,expectReply : 0
        }

Success Response

Content:

    
        {
        status  : "00",
        details : "IEKDLWO!"
        }

Possible Error Responses

Content: Bad Data, data supplied is invalid 

    
        {
        status  : "99"
        ,details : "Bad Data"
        }

Content: System Error
System error, contact SITCA

    
        {
        status  : "98"
        ,details : "System Error, contact SITCA for support"
        ,referenceCode : "1286705410"
        }

Content: No recipients specified in request

    
        {
        status  : "03"
        ,details : "No recipients"
        }

Content: Invalid date specified

    
        {
        status  : "02"
        ,details : "Invalid date"
        }

Content: Invalid credentials

    
        {
        status  : "01"
        ,details : "Check credentials"
        }

Sample Call

 

        $.ajax({
        url: "https://www.sitcaribbean.com/api"
        ,dataType: "json"
        ,data :
        {
        apiKey    : "K830291KE"
        ,apiSecret : "38ekaldk3and!"
        ,command   : "schedule"
        ,whenToSend : "2015-11-23 15:25:00"
        ,messageFrom: "AcmeLTD"
        ,recipient:
        {
        {
        number  : "1268123456"
        ,name    : "James Doe"
        ,group   : "Everyone"
        ,field01 : "Mr"
        ,field02 : "Wednesday"
        ,field03 : "10 AM"
        ,field04 : "Mr Samuel"
        ,field05 : "1-268-745-2546"
        ,field06 : ""
        ,field07 : ""
        ,field08 : ""
        ,field09 : ""
        ,field10 : ""
        },
        {
        number  : "12689874512"
        ,name    : "Janice Doethy"
        ,group   : "Everyone"
        ,field01 : "Mrs"
        ,field02 : "Tuesday"
        ,field03 : "9 AM"
        ,field04 : "Ms Spencer"
        ,field05 : "1-268-745-2174"
        ,field06 : ""
        ,field07 : ""
        ,field08 : ""
        ,field09 : ""
        ,field10 : ""
        },
        {
        number  : "12687451247"
        ,name    : "Jacob Doe"
        ,group   : "Everyone"
        ,field01 : "Mr"
        ,field02 : "Friday"
        ,field03 : "1 PM"
        ,field04 : "Mr Smith"
        ,field05 : "1-268-745-4196"
        ,field06 : ""
        ,field07 : ""
        ,field08 : ""
        ,field09 : ""
        ,field10 : ""
        }
        }
        }
        ,messageToSend :    "Hello [field01] [name]. This is just a gentle reminder for your appointment
                            next  [field02] with [field04] at [field03].  If you need to reschedule
                            please call [field04] at any time at [field05]. Yours truly, Dr Smith"
        ,notifyTelephone :
        {
        {12687451123}
        ,{12687452174}
        ,{12687459684}
        }
        ,notifyEmail:
        {
        {itsupport@drsmithantigua.com}
        ,{drsmith@drsmithantigua.com}
        ,{frontdesk@drsmithantigua.com}
        }
        ,sendAcceptanceConfirmation : 1
        ,expectReply : 0
        }
        });

Notes

In the event of a System Error, ensure you include in your support call/email the reference-code that was returned. If the parameter expectReply is set to 1 then the messageFrom parameter will be ignored and replaced with a random SITCA number.

This enables the recipient to reply to the message sent. Replies will be saved in your history. History can be downloaded manually. Support for history download via the API will be implemented in a future update.

Home | Methods