Butterflive account management API

This page provides documentation about the Butterflive account web services. If you wish to automate Butterflive account creation, Butterflive account services are the best solution.
For instance, if you use an e-commerce solution, you could create a Butterflive account directly from the e-commerce website, designing your own interface and avoiding your users the process course on the Butterflive website.

Butterflive provides some services to manage account via URL calls. All services are exposed via JSON over HTTP. Just perform a HTTPS request with the right GET parameters on Butterflive and it will answer JSON message.

Create an account
Validate an e-mail
Register a site
Get account key
Get account registered sites

The Butterflive account management processus



Creation: This process will send an account creation request to Butterflive. Only one URL call must be done, using the createAccountService function. Butterflive will send the validation mail (by default) or you can send it yourself using the returned validation token.

Validation: The validation process is the way to enable a Butterflive account and get the unique Butterflive key. To enable a Butterflive account, use the token sent by mail, or returned by the previous function and send it to Butterflive using the validateMailService function To get the unique Butterflive account key, use the getKeyByMail function wich will return you the key.

Securing: To begin using a key with a website, you need to authorize the website with the url_activate function. You have to provide the login and password of the account to activate a URL on an account.

Check: To retreive all registered sites for an account, use the getKeyInfo2 function. You have to provide the account key.

Below, we will detail all those functions.

Create an account

URL: https://www.butterflive.com/remote/createAccountService
The account is created in "awaiting validation" mode, which means it will not be available until the validateMailService function is called.
This action outputs a JSON message.
The message can be:

    {
    "status"=>"ok",
    "token"=>"[the token to validate by mail]"
    }
 

or:

    {
    "status"=>"error",
    "code"=>"the error code",
    "message"=>"a message to display"
    }
 

The error code can take many different values. You should check this special one:
- 'useralreadyexist': means the mail is already used in an existing account

Parameters:

Name Description
firstname The account owner's firstname
lastname The account owner's lastname
mail The account owner's e-mail
password A password for the account
companyname The account owner's company name
countrycode The account owner's country code
origin The identifier of the origin of the account creation request. For example if your request come from a Magento powered website, origin will be "magento".
websiteurl Your website URL. This is the website that will be authorized for this account. If set, website will be associated and activated at the account creation.Use this parameter if you know the site you will use with Butterflive to activate it now without using the Activate URL function
sendRegistrationMail (optional) Whether Butterflive should send the validation and registration mail, or whether this will be taken in charge by your code calling this function.
language (optional) The language for this account (otherwise, it will default to english).
validateMailUrl( optional) The complete path to the mail validation page. The mail validation link will be pointing this URL.

Example

To create an account for a user, request Butterflive.com at this URL: https://www.butterflive.com/remote/createAccountService?firstname=john&lastname=doe&mail=contact@butterflive.com &password=P@ssw0rd&companyname=butterflive&countrycode=fr &origin=services&websiteurl=http://www.johndoe.com

Validate an e-mail

URL : https://www.butterflive.com/remote/validateMailService
Validates a mail address (and activates the account!) This action outputs a JSON message. The message can be: 

            {
            "status"=>"ok",
            "code"=>"accountvalidated",
            "key"=>"[the butterflive key]"
            }
 

or:

            {
            "status"=>"pending",
            "code"=>"accountpending",
            }
 

or:

            {
            "status"=>"error",
            "code"=>"the error code",
            "message"=>"a message to display",
            "key"=>"[the butterflive key] (if any)"
            }
 

The code can take many different values. You should check these special ones:
- 'tokennotfound': means the mail is already used in an existing account
- 'accountalreadyvalidated': means the account is already validated (you can access the key in the "key" property of the JSON object)
The status can be "ok", "pending", or "error".
If the status is pending, Butterflive will not return any key. You have to call back again to get the key later.

Name Description
hashcode The hashcode used to validate mail

Example

To validate a mail address and an account with the hashcode "125a0a27986b3e49b6932aa2ba213b436594795a", request Butterflive.com at this URL: https://www.butterflive.com/remote/validateMailService?hashcode=125a0a27986b3e49b6932aa2ba213b436594795a

Manage account informations

Get the account key

URL : https://www.butterflive.com/remote/getKeyByMail
Returns the Butterflive key associated to a mail.
This action outputs a JSON message.
The message can be: 

            {
            "status"=>"ok",
            "key"=>"[the Butterflive key for the account]"
            }
 

or:

            {
            "status"=>"error",
            "code"=>"unknownuser",
            "message"=>"a message to display"
            }
 

Name Description
mail The account owner mail address

Example

To get the Butterflive key associated to the contact@butterflive.com account, request Butterflive.com at this URL:
https://www.butterflive.com/remote/getKeyByMail?mail=contact@butterflive.com

Add a site to the account

URL : https://www.butterflive.com/remote/url_activate This action adds the url as an authorized URL for the account bound to the user whose login and password are specified.
If the account is a free account, and if the site is already set, the site is replaced.
A JSON message is returned. Format: 

 
            {
            "status"=> "ok|error",
            "code"=> "badcredentials|..."
            "replace"=> "true|false",
            "message"=> "an error message"
            }
 

status: It can be "ok" or "error".
code: if status=error, this is an error code. code="badcredentials" if the login or password is incorrect.
message: if status=error, a message is passed explaining the error.
replace: if true, the URL replaced an older URL (because we are on a free account that supports only one web site).

Name Description
l The account owner mail address
p The account password
url The url to activate.

Example

To add the website "http://www.johndoe.com/tracker" to the John Doe account, request Butterflive.com at this URL: https://www.butterflive.com/remote/url_activate &l=contact@butterflive.com&p=P@assword&url=http://www.johndoe.com

Get account Registered URLs

URL : https://www.butterflive.com/remote/getKeyInfo2 This action return all the registered URLs for the account bound to the specified key A JSON message is returned. Format:

 
                  {
                  "active"=> "true|false",
                  "pro"=> "true|false",
                  "urls"=> "["url1","url2",...]"
                  }
 

or in case of invalid key:

 
                  {
                  "error"=> "Invalid key.",
                  "errorCode"=> "invlaid_key"
                  }
 

Name Description
key The Butterflive account key

Example

To get all registered sites on the Butterflive account key "C84BE4A1E163BC9B63", request Butterflive.com at this URL: https://www.butterflive.com/remote/getKeyInfo2?key=C84BE4A1E163BC9B63