Ecards API Manual

Administration functions look after non user specific actions as well as the register and login actions. This includes Terms and conditions, privacy statement and Checking the users subscription status.

terms()

This will return the terms and conditions text. This will be in HTML format.

              {"success":{"result":true},"message":{"error_code":"OK"},"data":{"terms":"\r\n HTML CODE HERE... "}}
        

privacy()

This will return the privacy policy text. This will be in HTML format.

              {"success":{"result":true},"message":{"error_code":"OK"},"data":{"privacy":"\r\n HTML CODE HERE... "}}
        

aboutUs()

This will return the About Us text. This will be in HTML format.

              {"success":{"result":true},"message":{"error_code":"OK"},"data":{"aboutUs":"\r\n HTML CODE HERE... "}}

          

chkSub(email)

This will check the users subscription status and return the True plus the join date if the users subscription is still valid and False plus the users original join date if the subscription is not valid.

           {"success":{"result":true},"message":{"error_code":"OK"},"data":{"subscription":"2012-02-21 09:07:10"}}
           Or
           {"success":{"result":false},"message":{"error_code":"EXPIRED"},"data":{"subscription":"2010-02-18 14:13:10"}}

          

login(email:password)

Logs the user into the application. Returns a result flag as true and a success message with the user ID if its successful. If there is an unsuccessful attempt a false flag will be returned with an error message

          {"success":{"result":true},"message":{"error_code":"OK"},"data":{"user_id":"21"}}
          Or
          {"success":{"result":false},"message":{"error_code":"NO_USER"},"data":{"user_id":"User does not exist"}}
        

raiseTicket(id:type:issue)

This function raises a support ticket with birthdayEcard.com Users and owners can send us a message if bugs are found or to request new features etc

             {"success":{"result":true},"message":{"error_code":"OK"},"data":{"ticket":"ticket raised"}}
            Or
            {"success":{"result":false},"message":{"error_code":"NO_TICKET"},"data":{"ticket":"Could not raise ticket"}}

          

register(email)

This function creates an account and returns the users new password on success or an error message if the user has already registered

            {"success":{"result":true},"message":{"error_code":"OK"},"data":{"register":"7364df2eec6bdc11c60a231eb8dca8ed"}}
            Or
            {"success":{"result":false},"message":{"error_code":"EXISTS_IN_DB"},"data":{"register":"Already registered"}}

          

User functions deal with all the actions concerned directly with the user. This includes actions like setting and getting the users details and options as well as all of the contact functions/

updateUserDetails(user_id:firstname:lastname:email)

Updates the Users first name, last name and email address.

returns True (successful) with the users ID or False (unsuccessful) with a message

                {"success":{"result":true},"message":{"error_code":"OK"},"data":{"user_details":"3"}}
                Or
                {"success":{"result":false},"message":{"error_code":"NO_USER"},"data":{"user_details":"User does not exist"}}
          

userDetails(user_id)

Returns the users details

returns True (successful) with the users ID or False (unsuccessful) with a message

                {"success":{"result":true},"message":{"error_code":"OK"},"data":{"user_details":{"first_name":"Eddie","last_name":"Blundellsan","email":"test@test.com"}}}
                Or
                {"success":{"result":false},"message":{"error_code":"NO_USER"},"data":{"user_details":"User does not exist"}}

          

options(user_id)

Returns the users options to receive advertising emails.

returns True (successful) with the advertising option - Birthday Reminder or False (unsuccessful) with a message if there is a problem

               {"result":true},"message":{"error_code":"OK"},"data":{"options":"0"}}
               Or
               {"success":{"result":false},"message":{"error_code":"NO_USER"},"data":{"options":"User does not exist"}}
          

updateOptions(user_id:(boolean 1 or 0) advertising)

Sets the users options to receive advertising emails (1) or not (0).

returns True (successful) with the users ID or False (unsuccessful) with a message if there is a problem

              {"success":{"result":true},"message":{"error_code":"OK"},"data":{"options":"1"}}
               Or
              {"success":{"result":false},"message":{"error_code":"NO_USER"},"data":{"options":"User does not exist"}}
          

Card functions deal with all the processes connected with sending the ecard.

This includes

• The cards available for sending
• The related cards for displaying on the preview page.
• The popularity rating for each card
• The users previously sent cards
• A search facility for the ecards
• A selection of previously sent cards from other users for a live feed in the site

cards([category])

returns a list of all the cards available, if the optional category is used then it will return a list of cards in the desired category.

eg. cards(romance) will return all of the romance cards in the system which will return

            This is a selection of the returned results for demonstration purposes
          {"success":{"result":true},"message":{"error_code":"OK"},"data":{"cards":["[\"2386\",\"Romance\",\"Dog saying I love you\",\"This is such a cute video eCard to send that special person in your life. Here we see a cute Husky saying \\\"I love you\\\"! A great card to send to show someone how you feel whilst putting a big smile on their face.\",\"\",\"\",\"49,174,\",\"Animal,cute,video,ecard,video ecard,love,romance,talking dog,dog\",\"2\"]
          

usersCards(user_id)

This returns a list of all of the users sent cards

returns True (successful) with a list of sent cards or False (unsuccessful) with a message

  This is a selection of the returned results for demostration purposes
            {"success":{"result":true},"message":{"error_code":"OK"},"data":{"sent_cards":["[\"471\",\"Wishing you a FABULOUS BIRTHDAY WEEK!! from Bob & Sarah xxx\",\"2012-03-12 00:00:00\",\"0\"]",
            or 
            {"success":{"result":false},"message":{"error_code":"NO_CARDS"},"data":{"sent_cards":"no cards returned"}}
          

rating(card_id)

returns the popularity rating of the card out of 5 in .1 increments

returns True (successful) with the rating of the card or False (unsuccessful) with a message

            {"success":{"result":true},"message":{"error_code":"OK"},"data":{"rating":"4"}}
          

relatedCards(card_id)

returns a list of 4 cards that are related to the selected card, including a description, thumbnails and a link to the actual card

returns True (successful) with a list of the cards or False (unsuccessful) with a message

            This is a selection of the returned results for demonstration purposes
            {"success":{"result":true},"message":{"error_code":"OK"},"data":{"related_cards":["[\"2040\",\"Retro\",\"165;\",\"Birthday Retro\",\"Send your old school Birthday message with this Retro e Card\",\"ecard_2040_25_11_37_15.swf\",\"ecard_prev_2040_17_06_20_49.jpg\",\"Retro, cool, funky, Birthday, e cards\\\/e-cards\\\/ecards\\\/e card\\\/e-card\\\/ecard\",\"This is a funny Retro styled Birthday ecard that shows to people exchanging a small gift, to the left of them text reads: \\\"I got you a present for your birthday... I just don't know how to wrap a life.\\\"\",\"Retro, cool, funky, Birthday, e cards\\\/e-cards\\\/ecards\\\/e card\\\/e-card\\\/ecard\",\"Editor's Comment<\\\/b>

\\r\\nThis is a funny Retro styled Birthday ecard that shows to people exchanging a small gift, to the left of them text reads: \\\"I got you a present for your birthday... I just don't know how to wrap a life.\\\"\",\"Retro;funny;birthday;cool;\",\"Retro eCards\",\"The quick and easy way to send your greetings to anyone in the world!\",\"Send any of our ecards to suit every occasion for free, no membership needed!\",\"Picture of Retro eCard\",\"Send-Retro-Ecards-here-absolutely-free\",\"0\"]
          

cardByID(card_id)

Returns details of the card.

returns True (successful) with a list of the cards or False (unsuccessful) with a message

           {"success":{"result":true},"message":{"error_code":"OK"},"data":{"card":["[\"Yes \\\/ No\",\"Yes (Forced)\",\"This e-card is a man dangling over a load of spikes indicating that he is being tortured to do something. It can be used to tell people that you have no choice in the matter and that the answer is YES! In other words you would rather not but the answer is yes. It was designed to be used as a \\\"reply\\\" to a previous e-card - so if someone sends you a birthday invite you can send this back as a bit of fun!\",\"ecard_13_24_11_17_13.swf\",\"ecard_prev_Yes-Forced_462_28_16_57_30.jpg\",\"53\",\"yes,reply,no chance,of course,poor man,torture,card,cards,ecard,ecards,e-card,e-cards\",\"1\"]"]}}
          

search((string) Search Term)

Returns a list of cards that meet the search term

returns True (successful) with a list of the cards or False (unsuccessful) with a message

            eg.  search(roman) will return
            This is a selection of the returned results for demonstration purposes
          {"success":{"result":true},"message":{"error_code":"OK"},"data":{"search_results":["[\"Romance\",\"49;57;\",\"I Love You\",\"Tell someone I Love You\",\"ecard_11_16_07_15_25.swf\",\"ecard_prev_11_02_00_51_30.jpg\",\"Love eCards\",\"This e-card is a nice picturesque countryside scene of a sunny day and a lovely apple tree. The camera then pans onto one of the juicy apples and all of a sudden a snake pops out of the apple and starts kissing the camera lens and hearts start appearing a\",\"Love eCards\",null,\"Love;romance;happy;soppy;child friendly;valentines day\",\"Love eCards\",\"birthdayEcard.com has an ecard for almost every occassion and can be assigned to deliver ecards at any given date!\",\"\",\"Picture of I love you, ecard, ecards, e-card, e-cards, e card, e cards, romantic, sweet\",\"Send-Free-Romantic-e-Cards-Here\",\"0\"]
          

searchCategories((int) Category_id)

Returns cards that are in the category supplied

returns True (successful) with a list of the cards or False (unsuccessful) with a message

            eg.  search(roman) will return
            This is a selection of the returned results for demonstration purposes
          {"success":{"result":true},"message":{"error_code":"OK"},"data":{"category":["[\"Romantic   eCards\",\"Romance\",\"49\",\"Romance_ecards_23_1_icon.gif\",\"Send a   free romantic eCard here at birthdayEcard.com. 100's of love & romantic   e-cards available, completely free of charge and no membership required.   Try it today!\",\"Romantic, ecards\"]"]}}
          

categorys()

Returns a list of available categories

returns True (successful) with a list of the categories or False (unsuccessful) with a message

            This is a selection of the returned results for demonstration purposes
          {"success":{"result":true},"message":{"error_code":"OK"},"data":{"categories":["[\"Romantic eCards\",\"Romance\",\"49\",\"Romance_ecards_23_1_icon.gif\",\"Send a free romantic eCard here at birthdayEcard.com. 100's of love & romantic e-cards available, completely free of charge and no membership required. Try it today!\",\"Romantic, ecards\"]",
        

sampleCards((int) number_of_cards)

Returns a list of cards to display as a feed, number_of_cards is the maximum number of cards returned.

returns True (successful) with a list of the cards or False (unsuccessful) with a message

            This is a selection of the returned results for demonstration purposes
            {"success":{"result":true},"message":{"error_code":"OK"},"data":{"sample_cards":[\"611\",\"Hi Mum!\\r\\nWe wish you very happy birthday\\r\\nJulia & Sally\",\"2012-06-21 00:00:00\",\"0\"]
          

Sending Functions

These Function deal with the sending of the card.

Once the user has sent the card, the automated process sends an email to the recipient and also sends a receipt of the card to the users email account. Upon the recipient opening the ecard and viewing it, a final read receipt is sent to the user

emailcard((string) user_id:(string) recip_firstname:(string) recip_lastname:(string) recip_email:(string) message:(int) ecard_id:(boolean) terms_and_conditions_agree)

Sends an ecards according to the arguments passed in

Note that the terms and conditions MUST be agreed to before we can send the card.

returns True (successful) with a list of the cards or False (unsuccessful) with a message detailing the source of the error

           {"success":{"result":true},"message":{"error_code":"OK"},"data":{"email":"ecard sent"}}
             Or
           {"success":{"result":false},"message":{"error_code":"SEND_CARD_ERROR"},"data":{"email":"store_recip:OK,store_card:OK cannot send card"}}
           This shows that the API stored the recipient (store_recip:OK) and the card (store_card:OK) but failed to send the email (cannot send card).
          

sendFacebook(sender_firstname:sender_lastname:sender_email:recip_firstname:recip_lastname:recip_email:send_date:
message:ecard_id:terms_and_conditions_agree){

Send a card Via Facebook. This functionality will be available soon

sendTwitter(sender_firstname:sender_lastname:sender_email:recip_firstname:recip_lastname:recip_email:send_date:
message:ecard_id:terms_and_conditions_agree){

Send a card Via Twitter. This functionality will be available soon

The authorisation string is passed in the URL along with any function call. without the correct authorisation string the request will be ignored and a 'Not Authorised' message will be returned. All requests are logged by us for bug tracking and security.

We use 3 part security system consisting of a Token, a Nonce and a hash passed over via an encoded URL. These are passed in the URL along with the method.

token={Your API token}&method={API method to call}&nonce={Nonce}hash={The security hash}
          

e.g. (note that this is not real data)

                                                                                                     
token=286d52kd02m4&method=get_balance%287jf1770f872b80735dbe01f0%29&nonce=255.255.255.255-4830587385&hash=e934hfhrfu32h84hr234yhr023h3hrt0
          

The token is supplied by eCards when you first register to use the API. This will be unique to you and therefore should not be published or released publicly

The Nonce is [users IP]-[timestamp]

The hash is [API Token, method name, nonce, API secret] appended together and encrypted

All passwords for both the application owner (the company implementing the API) and the customers (The owners customers) are encrypted and securely stored.