subscribe

Synopsis:

This API will subscribe users to a particular campaign. Once a user is subscribed to a campaign they will receive all auto responders and scheduled messages for that campaign until they are unsubscribed through the API or through normal STOP or STOP ALL SMS request. You may not import someone who has unsubscribed themselves from a campaign however you may re-subscribe someone who has unsubscribed through this API.

Request: XML

<REQUEST>
    <ACTION>subscribe</ACTION>
    <API_KEY>apiKey</API_KEY>
    <CAMPAIGNREF>Campaign Reference ID</CAMPAIGNREF>
    <SUBSCRIBERREF>Subscriber Reference ID</SUBSCRIBERREF>
    <MOBILE>Number to subscribe</MOBILE>
    <DATA>
        <FIRST_NAME>First Name</FIRST_NAME>
        <LAST_NAME>Last Name</LAST_NAME>
        <GENDER>Gender</GENDER>
        ...
    </DATA>
    <SPID>Carrier ID</SPID>
    <TIMEZONE>Timezone abbreviation: EST, CST, MST, PST, etc.</TIMEZONE>
</REQUEST>

Request: GET

API_URL?action=subscribe
&api_key=API key
&campaignref=campaign reference ID
&subscriberref=subscriber reference ID
&mobile=number to subscribe
&data_first_name=first name
&data_last_name=last name
&data_gender=gender
...
&spid=carrier ID
&timezone=timezone abbreviation: EST, CST, MST, PST, etc.

Click here for more timezone options. Note that the difference between standard and daylight time does not matter here. The system will use the current time offset for the geographic region.

Request Parameters:

Mandatory: action, api_key, campaignRef, mobile
Optional: subscriberRef, data, spid, timezone

Response Parameters:

status, campaignRef, subscriberRef, mobile, errorcode, errorinfo

Request Example: XML

<REQUEST>
    <ACTION>subscribe</ACTION>
    <API_KEY>qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ</API_KEY>
    <CAMPAIGNREF>1116</CAMPAIGNREF>
    <SUBSCRIBERREF>ACCT-123232</SUBSCRIBERREF>
    <MOBILE>16502426055</MOBILE>
    <DATA>
        <FIRST_NAME>John</FIRST_NAME>
        <LAST_NAME>Smith</LAST_NAME>
        <AGE>29</AGE>
        <PET>Dog</PET>
    </DATA>
</REQUEST>

Request Example: GET

https://secure.skycore.com/API/wxml/1.3/index.php?action=subscribe
&api_key=qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ
&campaignref=1116
&subscriberref=ACCT-123232
&mobile=16502426055
&data_first_name=John
&data_last_name=Smith
&data_age=29
&data_pet=Dog

Response Example: Success

<RESPONSE>
    <STATUS>Success</STATUS>
    <CAMPAIGNREF>1116</CAMPAIGNREF>
    <SUBSCRIBERREF>ACCT-123232</SUBSCRIBERREF>
    <MOBILE>16502426055</MOBILE>
</RESPONSE>

Response Example: Failure

<RESPONSE>
    <STATUS>Failure</STATUS>
    <ERRORCODE>E721</ERRORCODE>
    <MOBILE>16502426055</MOBILE>
    <CAMPAIGNREF>1116</CAMPAIGNREF>
    <ERRORINFO>Invalid campaignref</ERRORINFO>
</RESPONSE>

Postback Notification:

Upon subscribing a number the system will generate a notification. For more details please visit the Mobile Subscribe section of the Opt-in Status Postback documentation.


General Error Codes:

Code Description
E100 Invalid request. Make a valid request via GET/POST/XML with all the required variables.
E104 User Authentication Failed.
E105 This account has no API rights.
E106 You can call API every X seconds.
E107 This account has no rights to use this action.
E108 XML Parse error: $error.
E109 API not activated.
E112 IP was not whitelisted. API call rejected.
E113 Set throughput exceeded for this API action. API call rejected.
E114 Phone number is blacklisted. API call rejected.
E120 Account has reached the API request limit.
E503 Internal error.


Code Description
E718 The ‘campaignref’ is required
E721 Invalid campaignref
E901 The ‘mobile’ number is required
E902 The ‘campaignid’ is required
E903 Invalid ‘campaignid’
E904 Could not subscribe this number


Key Term Definitions:

Term Description
ACTION This is the name of the function you want to execute with the API.
API_KEY Random key that is assigned to an account that can be used for authorization instead of USER/PASS. You can find and regenerate this key on the ‘API Settings’ page.
CAMPAIGNID The ID(integer) of the campaign to which the user will be subscribed.
CAMPAIGNREF Depending on your API settings, you may be required to subscribe users into a campaign first before sending them messages. If you are required to subscribe a user first, then a valid Campaign Reference is required. This would be the campaign reference ID (string) to which the user is subscribed.
MOBILE A Phone Number used inside the ‘subscribe’/’unsubscribe’ function.
SPID The carrier ID(integer). See Operator ID’s.
SUBSCRIBERREF The customer reference ID for the subscriber. This ID can reference one or more subscriber phone numbers.
TIMEZONE A time zone abbreviation associated with the phone number used inside the ‘subscribe’ function.


Timezones:

Abbreviation Name UTC offset
ACDT Australian Central Daylight Savings Time UTC+10:30
ACST Australian Central Standard Time UTC+09:30
ACT Acre Time UTC−05
ACT ASEAN Common Time UTC+08
ADT Atlantic Daylight Time UTC−03
AEDT Australian Eastern Daylight Savings Time UTC+11
AEST Australian Eastern Standard Time UTC+10
AFT Afghanistan Time UTC+04:30
AKDT Alaska Daylight Time UTC−08
AKST Alaska Standard Time UTC−09
AMST Amazon Summer Time (Brazil) UTC−03
AMT Amazon Time (Brazil) UTC−04
AMT Armenia Time UTC+04
ART Argentina Time UTC−03
AST Arabia Standard Time UTC+03
AST Atlantic Standard Time UTC−04
AWDT Australian Western Daylight Time UTC+09
AWST Australian Western Standard Time UTC+08
AZOST Azores Standard Time UTC−01
AZT Azerbaijan Time UTC+04
BDT Brunei Time UTC+08
BDT Bangladesh Daylight Time UTC+06
BIOT British Indian Ocean Time UTC+06
BIT Baker Island Time UTC−12
BOT Bolivia Time UTC−04
BRST Brasilia Summer Time UTC−02
BRT Brasilia Time UTC−03
BST Bangladesh Standard Time UTC+06
BST Bougainville Standard Time UTC+11
BST British Summer Time (British Standard Time from Feb 1968 to Oct 1971) UTC+01
BTT Bhutan Time UTC+06
CAT Central Africa Time UTC+02
CCT Cocos Islands Time UTC+06:30
CDT Central Daylight Time (North America) UTC−05
CDT Cuba Daylight Time UTC−04
CEDT Central European Daylight Time UTC+02
CEST Central European Summer Time (Cf. HAEC) UTC+02
CET Central European Time UTC+01
CHADT Chatham Daylight Time UTC+13:45
CHAST Chatham Standard Time UTC+12:45
CHOT Choibalsan UTC+08
ChST Chamorro Standard Time UTC+10
CHUT Chuuk Time UTC+10
CIST Clipperton Island Standard Time UTC−08
CIT Central Indonesia Time UTC+08
CKT Cook Island Time UTC−10
CLST Chile Summer Time UTC−03
CLT Chile Standard Time UTC−04
COST Colombia Summer Time UTC−04
COT Colombia Time UTC−05
CST Central Standard Time (North America) UTC−06
CST China Standard Time UTC+08
CST Central Standard Time (Australia) UTC+09:30
CST Central Summer Time (Australia) UTC+10:30
CST Cuba Standard Time UTC−05
CT China time UTC+08
CVT Cape Verde Time UTC−01
CWST Central Western Standard Time (Australia) unofficial UTC+08:45
CXT Christmas Island Time UTC+07
DAVT Davis Time UTC+07
DDUT Dumont d’Urville Time UTC+10
DFT AIX specific equivalent of Central European Time UTC+01
EASST Easter Island Standard Summer Time UTC−05
EAST Easter Island Standard Time UTC−06
EAT East Africa Time UTC+03
ECT Eastern Caribbean Time (does not recognise DST) UTC−04
ECT Ecuador Time UTC−05
EDT Eastern Daylight Time (North America) UTC−04
EEDT Eastern European Daylight Time UTC+03
EEST Eastern European Summer Time UTC+03
EET Eastern European Time UTC+02
EGST Eastern Greenland Summer Time UTC+00
EGT Eastern Greenland Time UTC−01
EIT Eastern Indonesian Time UTC+09
EST Eastern Standard Time (North America) UTC−05
EST Eastern Standard Time (Australia) UTC+10
FET Further-eastern European Time UTC+03
FJT Fiji Time UTC+12
FKST Falkland Islands Standard Time UTC−03
FKST Falkland Islands Summer Time UTC−03
FKT Falkland Islands Time UTC−04
FNT Fernando de Noronha Time UTC−02
GALT Galapagos Time UTC−06
GAMT Gambier Islands UTC−09
GET Georgia Standard Time UTC+04
GFT French Guiana Time UTC−03
GILT Gilbert Island Time UTC+12
GIT Gambier Island Time UTC−09
GMT Greenwich Mean Time UTC
GST South Georgia and the South Sandwich Islands UTC−02
GST Gulf Standard Time UTC+04
GYT Guyana Time UTC−04
HADT Hawaii-Aleutian Daylight Time UTC−09
HAEC Heure Avancée d’Europe Centrale francised name for CEST UTC+02
HAST Hawaii-Aleutian Standard Time UTC−10
HKT Hong Kong Time UTC+08
HMT Heard and McDonald Islands Time UTC+05
HOVT Khovd Time UTC+07
HST Hawaii Standard Time UTC−10
IBST International Business Standard Time UTC
ICT Indochina Time UTC+07
IDT Israel Daylight Time UTC+03
IOT Indian Ocean Time UTC+03
IRDT Iran Daylight Time UTC+04:30
IRKT Irkutsk Time UTC+08
IRST Iran Standard Time UTC+03:30
IST Indian Standard Time UTC+05:30
IST Irish Standard Time UTC+01
IST Israel Standard Time UTC+02
JST Japan Standard Time UTC+09
KGT Kyrgyzstan time UTC+06
KOST Kosrae Time UTC+11
KRAT Krasnoyarsk Time UTC+07
KST Korea Standard Time UTC+09
LHST Lord Howe Standard Time UTC+10:30
LHST Lord Howe Summer Time UTC+11
LINT Line Islands Time UTC+14
MAGT Magadan Time UTC+12
MART Marquesas Islands Time UTC−09:30
MAWT Mawson Station Time UTC+05
MDT Mountain Daylight Time (North America) UTC−06
MET Middle European Time Same zone as CET UTC+01
MEST Middle European Summer Time Same zone as CEST UTC+02
MHT Marshall Islands UTC+12
MIST Macquarie Island Station Time UTC+11
MIT Marquesas Islands Time UTC−09:30
MMT Myanmar Time UTC+06:30
MSK Moscow Time UTC+03
MST Malaysia Standard Time UTC+08
MST Mountain Standard Time (North America) UTC−07
MST Myanmar Standard Time UTC+06:30
MUT Mauritius Time UTC+04
MVT Maldives Time UTC+05
MYT Malaysia Time UTC+08
NCT New Caledonia Time UTC+11
NDT Newfoundland Daylight Time UTC−02:30
NFT Norfolk Time UTC+11:00
NPT Nepal Time UTC+05:45
NST Newfoundland Standard Time UTC−03:30
NT Newfoundland Time UTC−03:30
NUT Niue Time UTC−11
NZDT New Zealand Daylight Time UTC+13
NZST New Zealand Standard Time UTC+12
OMST Omsk Time UTC+06
ORAT Oral Time UTC+05
PDT Pacific Daylight Time (North America) UTC−07
PET Peru Time UTC−05
PETT Kamchatka Time UTC+12
PGT Papua New Guinea Time UTC+10
PHOT Phoenix Island Time UTC+13
PKT Pakistan Standard Time UTC+05
PMDT Saint Pierre and Miquelon Daylight time UTC−02
PMST Saint Pierre and Miquelon Standard Time UTC−03
PONT Pohnpei Standard Time UTC+11
PST Pacific Standard Time (North America) UTC−08
PST Philippine Standard Time UTC+08
PYST Paraguay Summer Time (South America) UTC−03
PYT Paraguay Time (South America) UTC−04
RET Réunion Time UTC+04
ROTT Rothera Research Station Time UTC−03
SAKT Sakhalin Island time UTC+11
SAMT Samara Time UTC+04
SAST South African Standard Time UTC+02
SBT Solomon Islands Time UTC+11
SCT Seychelles Time UTC+04
SGT Singapore Time UTC+08
SLST Sri Lanka Standard Time UTC+05:30
SRET Srednekolymsk Time UTC+11
SRT Suriname Time UTC−03
SST Samoa Standard Time UTC−11
SST Singapore Standard Time UTC+08
SYOT Showa Station Time UTC+03
TAHT Tahiti Time UTC−10
THA Thailand Standard Time UTC+07
TFT Indian/Kerguelen UTC+05
TJT Tajikistan Time UTC+05
TKT Tokelau Time UTC+13
TLT Timor Leste Time UTC+09
TMT Turkmenistan Time UTC+05
TOT Tonga Time UTC+13
TVT Tuvalu Time UTC+12
UCT Coordinated Universal Time UTC
ULAT Ulaanbaatar Time UTC+08
USZ1 Kaliningrad Time UTC+02
UTC Coordinated Universal Time UTC
UYST Uruguay Summer Time UTC−02
UYT Uruguay Standard Time UTC−03
UZT Uzbekistan Time UTC+05
VET Venezuelan Standard Time UTC−04:30
VLAT Vladivostok Time UTC+10
VOLT Volgograd Time UTC+04
VOST Vostok Station Time UTC+06
VUT Vanuatu Time UTC+11
WAKT Wake Island Time UTC+12
WAST West Africa Summer Time UTC+02
WAT West Africa Time UTC+01
WEDT Western European Daylight Time UTC+01
WEST Western European Summer Time UTC+01
WET Western European Time UTC
WIT Western Indonesian Time UTC+07
WST Western Standard Time UTC+08
YAKT Yakutsk Time UTC+09
YEKT Yekaterinburg Time UTC+05
Z Zulu Time (Coordinated Universal Time) UTC